<html>
<head>
	<title>SQL Relay Configuration Guide</title>
	<link rel="stylesheet" href="../css/styles.css">
</head>
<body>
<h1>SQL Relay Configuration Guide</h1>

<ul>
  <li><a href="#quick">Quick Start</a></li>
  <li><a href="#basic">Basic Configuration</a></li>
  <ul>
    <li><a href="#dbconnections">Database Connections</a></li>
    <ul>
      <li><a href="#dbconnections-performance">For Performance</a></li>
      <li><a href="#dbconnections-throttling">Throttling</a></li>
    </ul>

    <li><a href="#dbcursors">Database Cursors</a></li>
    <li><a href="#dynamicscaling">Dynamic Scaling</a></li>
    <li><a href="#listener">Listener Configuration</a></li>
    <li><a href="#database">Database Configuration</a></li>
    <ul>
      <li><a href="#db-oracle">Oracle</a></li>
      <li><a href="#db-mssql">Microsoft SQL Server (using FreeTDS)</a></li>
      <li><a href="#db-sap">SAP/Sybase</a></li>
      <li><a href="#db-db2">IBM DB2</a></li>
      <li><a href="#db-informix">Informix</a></li>
      <li><a href="#db-mysql">MySQL</a></li>
      <li><a href="#db-postgresql">PostgreSQL</a></li>
      <li><a href="#db-firebird">Firebird</a></li>
      <li><a href="#db-sqlite">SQLite</a></li>
      <li><a href="#db-odbc">ODBC</a></li>
      <li><a href="#db-msaccess">Microsoft Access (using MDBTools)</a></li>
    </ul>

    <li><a href="#instances">Multiple Instances</a></li>
    <li><a href="#autostart">Starting Instances Automatically</a></li>
  </ul>

  <li><a href="#altconfigfile">Alternate Configuration File Options</a></li>
  <ul>
    <li><a href="#directory">Configuration Directory</a></li>
    <li><a href="#specifying">Specifying Configuration Files</a></li>
    <li><a href="#remote">Remote Configuration Files</a></li>
    <li><a href="#linkfiles">Link Files</a></li>
  </ul>

  <li><a href="#ha">High Availability</a></li>
  <ul>
    <li><a href="#cluster">Load-Balancing and Fail-Over With Replicated Databases or Database Clusters</a></li>
    <li><a href="#rac">Already-Load-Balanced Databases</a></li>
    <li><a href="#masterslave">Master-Slave Query Routing</a></li>
    <li><a href="#frontend">Front-End Load-Balancing and Fail-Over</a></li>
  </ul>

  <li><a href="#authoptions">Authentication/Authorization Options</a></li>
  <ul>
    <li><a href="#userlistauth">User List Auth</a></li>
    <li><a href="#dbauth">Database Auth</a></li>
    <li><a href="#proxiedauth">Proxied Auth</a></li>
    <li><a href="#krb">Kerberos and Active Directory Encryption and Authentication</a></li>
    <li><a href="#tls">TLS/SSL Encryption and Authentication</a></li>
  </ul>

  <li><a href="#security">Security Features</a></li>
  <ul>
    <li><a href="#krbtls">Kerberos/Active Directory and TLS/SSL Encryption and Authentication</a></li>
    <li><a href="#runas">Run-As User and Group</a></li>
    <li><a href="#deniedallowedips">Denied/Allowed IP Addresses</a></li>
    <li><a href="#pwdenc">Password Encryption</a></li>
    <li><a href="#schedules">Connection Schedules</a></li>
    <li><a href="#filtering">Query Filtering</a></li>
  </ul>

  <li><a href="#translation">Translation</a></li>
  <ul>
    <li><a href="#querytranslation">Query Translation</a></li>
    <li><a href="#resultsettranslation">Result Set Translation</a></li>
  </ul>

  <li><a href="#queryrouting">Query Routing</a></li>
  <ul>
    <li><a href="#regex">regex</a></li>
    <li><a href="#userlist">userlist</a></li>
    <li><a href="#clientiplist">clientiplist</a></li>
    <li><a href="#clientinfolist">clientinfolist</a></li>
    <li><a href="#usedatabase">usedatabase</a></li>
    <li><a href="#routingquirks">Quirks and Limitations</a></li>
  </ul>

  <li><a href="#logging">Logging</a></li>
  <li><a href="#notifications">Notifications</a></li>
  <li><a href="#sessionqueries">Session-Queries</a></li>
  <li><a href="#advanced">Advanced Configuration</a></li>
</ul>

<hr/>

<br/><a name="quick"/><h2>Quick Start</h2>

<p>When SQL Relay is first installed, no configuration file exists.  You must create one in the appropriate location.  This location depends on the platform and on how you installed SQL Relay.</p>

<ul>
  <li>Unix and Linux</li>
  <ul>
    <li>Built from source - <b>/usr/local/firstworks/etc/sqlrelay.conf</b> (unless you specified a non-standard --prefix or --sysconfdir during the build)</li>
    <li>RPM package - <b>/etc/sqlrelay.conf</b></li>
    <li>FreeBSD package - <b>/usr/local/etc/sqlrelay.conf</b></li>
    <li>NetBSD package - <b>/usr/pkg/etc/sqlrelay.conf</b></li>
    <li>OpenBSD package - <b>/usr/local/etc/sqlrelay.conf</b></li>
  </ul>

  <li>Windows</li>
  <ul>
    <li>Built from source - <b>C:\Program Files\Firstworks\etc\sqlrelay.conf</b></li>
    <li>Windows Installer package - <b>C:\Program Files\Firstworks\etc\sqlrelay.conf</b> (unless you specified a non-standard installation folder)</li>
  </ul>

</ul>

<p>The most minimal sqlrelay.conf would be something like:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>This configuration defines an instance of SQL Relay named <i>example</i>, secured by a user and password, that opens and maintains a pool of 5 persistent connections to the <i>orcl</i> instance of an Oracle database using <i>scott</i><i>/tiger</i> credentials.</p>

<p>The instance can be started using:</p>

<blockquote>
  <pre>sqlr-start -id example
</pre>

</blockquote>
<blockquote>
( <b>NOTE:</b> When installed from RPM packages, SQL Relay may have to be started and stopped as root.)
</blockquote>
<p>It can be accessed locally using:</p>

<blockquote>
  <pre>sqlrsh -host localhost -user sqlruser -password sqlrpassword
</pre>

</blockquote>
<p>By default, SQL Relay listens on all available network interfaces, on port 9000, and it can be accessed remotely by hostname.  For example, if the server running SQL Relay is named <i>sqlrserver</i> then it can be accessed from another system using:</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver -user sqlruser -password sqlrpassword
</pre>

</blockquote>
<p>The instance can be stopped using:</p>

<blockquote>
  <pre>sqlr-stop -id example
</pre>

</blockquote>
<p>All running instances of SQL Relay can be stopped using:</p>

<blockquote>
  <pre>sqlr-stop
</pre>

</blockquote>
<p>(without the -id argument)</p>

<hr/>

<br/><a name="basic"/><h2>Basic Configuration</h2>

<p>The example above may be sufficient for many use cases, but SQL Relay has many options and for a production deployment, odds are you'll want to configure it further.</p>

<a name="dbconnections"/><h3>Database Connections</h3>

<p>By default, SQL Relay opens and maintains a pool of 5 <a href="../features/connectionpooling.html">persistent database connections</a>, but the number of connections can be configured using the connections attribute.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">connections</font><font color="#990000">=</font><font color="#FF0000">"10"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The number of connections determines how many client applications can access the database simultaneously.  In this example, up to 10, assuming each client only needs one connection.  Additional clients would be queued and would have to wait for one of the first 10 to disconnect before being able to access the database.</p>

<blockquote>
  <p>( <b>NOTE:</b> Any number of connections may be configured, up to an "absolute max connections" limit defined at compile-time, which defaults to 4096.  To find the limit on your system, run:</p>

  <blockquote>
    <pre>sqlr-start -abs-max-connections
</pre>

  </blockquote>
The command above also returns the "shmmax requirement" for the configuration.  "shmmax" refers to the maximum size of a single shared memory segment, a tunable kernel parameter on most systems.  The default shmmax requirement is about 5mb.  On modern systems, shmmax defaults to at least 32mb, but on older systems it commonly defaulted to 512k.  In any case, if the shmmax requirement exceeds the value of your system's shmmax parameter, then you will have to reconfigure the parameter before SQL Relay will start successfully.   This may be done at runtime on most modern systems, but on older systems you may have to reconfigure and rebuild the kernel, and reboot.)
</blockquote>
<a name="dbconnections-performance"/><h3>For Performance</h3>

<p>In a performance-oriented configuration, a good rule of thumb is to open as many connections as you can.  That number is usually environment-specific, and dictated by database, system and network resources.</p>

<a name="dbconnections-throttling"/><h3>Throttling</h3>

<p>If you intend to <a href="../features/throttling.html">throttle</a> database access to a particular application, then you may intentionally configure a small number of connections.</p>

<br/><a name="dbcursors"/><h3>Database Cursors</h3>

<p>Database cursors are used to execute queries and step through result sets.  Most applications only need to use one cursor at a time.  Some apps require more though, either because they run nested queries, or sometimes because they just don't properly free them.</p>

<p>SQL Relay maintains persistent cursors as well as connections.  By default, each connection opens one cursor, but the number of cursors opened by each connection can be configured using the cursors attribute.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">connections</font><font color="#990000">=</font><font color="#FF0000">"10"</font> <font color="#009900">cursors</font><font color="#990000">=</font><font color="#FF0000">"2"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>Any number of cursors can be opened.  A good rule of thumb is to open as few as possible, but as many as you know that your application will need.</p>

<blockquote>
( <b>NOTE:</b> The documentation above says that by default, each connection opens one cursor, and this is true, but it would be more accurate to say that by default each connection opens one cursor, but will open additional cursors on-demand, up to 5.  This is because it is common for an app to run at least one level of nested queries.  For example, it is common to run a select and then run an insert, update, or delete for each row in the result set.  Unfortunately, it is also not uncommon for apps to just manage cursors poorly.  So, SQL Relay's default configuration offers a bit of flexibility to accommodate these circumstances.  See the next section on Dynamic Scaling for more information about configuring connections and cursors to scale up and down on-demand.)
</blockquote>
<br/><br/><a name="dynamicscaling"/><h3>Dynamic Scaling</h3>

<p>Both connections and cursors can be configured to scale dynamically - open on demand and then die off when no longer needed.  This feature is useful if you have spikes in traffic during certain times of day or if your application has a few modules that occasionally need more cursors than usual.</p>

<p>The maxconnections and maxcursors attribute define the upper bounds.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">connections</font><font color="#990000">=</font><font color="#FF0000">"10"</font> <font color="#009900">maxconnections</font><font color="#990000">=</font><font color="#FF0000">"20"</font> <font color="#009900">cursors</font><font color="#990000">=</font><font color="#FF0000">"2"</font> <font color="#009900">maxcursors</font><font color="#990000">=</font><font color="#FF0000">"10"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>In this example, 10 connections will be started initially but more will be be started on-demand, up to 20.  Each of the newly spawned connections will die off if they are inactive for longer than 1 minute.</p>

<p>In this example, each connection will initially open 2 cursors but more will be opened on-demand, up to 10.  Each newly opened cursor will be closed as soon as it is no longer needed.</p>

<p>Other attributes that control dynamic scaling behavior include:</p>

<ul>
  <li>maxqueuelength</li>
  <li>growby</li>
  <li>ttl</li>
  <li>cursors_growby</li>
</ul>

<p>See the <a href="configreference.html">SQL Relay Configuration Reference</a> for more information on these attributes.</p>

<br/><a name="listener"/><h3>Listener Configuration</h3>

<p>By default, SQL Relay listens for client connections on port 9000, on all available network interfaces.</p>

<p>It can be configured to listen on a different port though...</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">"9001"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>...and accessed using:</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver -port 9001 -user sqlruser -password sqlrpassword
</pre>

</blockquote>
<p>It can also be configured to listen on a unix socket...</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/example.socket"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>...and accessed from the local server using:</p>

<blockquote>
  <pre>sqlrsh -socket /tmp/example.socket -user sqlruser -password sqlrpassword
</pre>

</blockquote>
<p>If the server has multiple network interfaces, SQL Relay can also be configured to listen on specific IP addresses.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">addresses</font><font color="#990000">=</font><font color="#FF0000">"192.168.1.50,192.168.1.51"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>When configured this way, it can be accessed on 192.168.1.50 and 192.168.1.51 but not on 127.0.0.1 (localhost).</p>

<p>If the socket option is specified but port and addresses options are not, then SQL Relay will only listen on the socket.  If addresses/port and socket options are both specified then it listens on both.</p>

<br/><a name="database"/><h3>Database Configuration</h3>

<p>By default, SQL Relay assumes that it's connecting to an Oracle database, but many other databases are supported.  The dbase attribute of the instance tag specifies the database type and the connect string options (options in the string attribute of the connection tag) specify the parameters used to connect to the database.  The connect string options are different for each database.</p>

<p>Examples follow.</p>

<br/><a name="db-oracle"/><h4>Oracle</h4>

<p>In this example, SQL Relay is configured to connect to an Oracle database.  The dbase parameter defaults to "oracle", so the dbase attribute may be omitted when connecting to an Oracle database.  It is just set here for illustrative purposes.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"oracle"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_home=/u01/app/oracle/product/12.1.0;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The oracle_home option refers to the base directory of an Oracle instance.  On Windows platforms, it should be specified as a Windows-style path with doubled backslashes.  For example:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>C<font color="#990000">:\\</font>Oracle<font color="#990000">\\</font>ora12<font color="#990000">.</font><font color="#993399">1</font></tt></pre>

</blockquote>
<p>The oracle_home option is often unnecessary though, as the $ORACLE_HOME environment variable is usually set system-wide.</p>

<p>The oracle_sid option refers to an entry in the tnsnames.ora file (usually $ORACLE_HOME/network/admin/tnsnames.ora) similar to:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>ORCL <font color="#990000">=</font>
  <font color="#990000">(</font>DESCRIPTION <font color="#990000">=</font>
    <font color="#990000">(</font>ADDRESS <font color="#990000">=</font> <font color="#990000">(</font>PROTOCOL <font color="#990000">=</font> TCP<font color="#990000">)(</font>HOST <font color="#990000">=</font> testhost<font color="#990000">)(</font>PORT <font color="#990000">=</font> <font color="#993399">1521</font><font color="#990000">))</font>
    <font color="#990000">(</font>CONNECT_DATA <font color="#990000">=</font>
      <font color="#990000">(</font>SERVER <font color="#990000">=</font> DEDICATED<font color="#990000">)</font>
      <font color="#990000">(</font>SERVICE_NAME <font color="#990000">=</font> orcl<font color="#990000">)</font>
    <font color="#990000">)</font>
  <font color="#990000">)</font></tt></pre>

</blockquote>
<p>(Note that the tnsnames.ora file must be readable by the user that the instance of SQL Relay is run as.)</p>

<p>If you are using Oracle Instant Client, then it's likely that you don't have an $ORACLE_HOME or a tnsnames.ora file.  In that case, the oracle_sid can be set directly to a tnsnames-style expression and the oracle_home option can be omitted.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"oracle"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=(DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = testhost)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = orcl)))"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>See the <a href="configreference.html#oracle">SQL Relay Configuration Reference</a> for other valid Oracle connect string options.</p>

<p>See <a target="_blank" href="http://systems.firstworks.com/p/getting-started-with-oracle.html">Getting Started With Oracle</a> for general assistance installing and configuring an Oracle database.</p>

<br/><a name="db-mssql-freetds"/><h4>Microsoft SQL Server (using FreeTDS)</h4>

<p>On Windows platforms, ODBC can be used to access a Microsoft SQL Server database.  There is also a <a target="_blank" href="https://msdn.microsoft.com/en-us/library/hh568451(v=sql.110).aspx">Microsoft-provided ODBC driver</a> for some versions of Linux.</p>

<p>However, on Linux and Unix platforms, access to Microsoft SQL Server databases is also available using <a target="_blank" href="http://www.freetds.org">FreeTDS</a>.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"freetds"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"server=TESTDB;user=testuser;password=testpassword;db=testdb"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The server option refers to an entry in the freetds.conf file (usually /etc/freetds.conf or /usr/local/etc/freetds.conf) which identifies the database server, similar to:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><font color="#990000">[</font>TESTDB<font color="#990000">]</font>
	host <font color="#990000">=</font> testhost
	port <font color="#990000">=</font> <font color="#993399">1433</font>
	<font color="#008080">tds</font> version <font color="#990000">=</font> <font color="#993399">7.0</font>
	<font color="#008080">client</font> charset <font color="#990000">=</font> UTF<font color="#990000">-</font><font color="#993399">8</font></tt></pre>

</blockquote>
<p>(Note that the freetds.conf file must be readable by the user that the instance of SQL Relay is run as.)</p>

<p>See the <a href="configreference.html#freetds">SQL Relay Configuration Reference</a> for other valid FreeTDS connect string options.</p>

<br/><a name="db-sap"/><h4>SAP/Sybase (using the native SAP/Sybase library)</h4>

<p>In this example, SQL Relay is configured to connect to a SAP/Sybase database using the native SAP/Sybase library.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"sap"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"sybase=/opt/sap;lang=en_US;server=TESTDB;user=testuser;password=testpassword;db=testdb"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The sybase option refers to the base directory of the SAP/Sybase software installation.  On Windows platforms, it should be specified as a Windows-style path with doubled backslashes.  For example:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>C<font color="#990000">:\\</font>SAP</tt></pre>

</blockquote>
<p>The sybase option is often unnecessary though, as the $SYBASE environment variable is usually set system-wide.</p>

<p>On Linux/Unix platforms, the server option refers to an entry in the interfaces (usually $SYBASE/interfaces) file which identifies the database server, similar to:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>TESTDB
	master tcp ether testhost <font color="#993399">5000</font>
	query tcp ether testhost <font color="#993399">5000</font></tt></pre>

</blockquote>
<p>(Note that the interfaces file must be readable by the user that the instance of SQL Relay is run as.)</p>

<p>On Windows platforms, the server option refers to a similar entry created in an opaque location with the Open Client Directory Services Editor (dsedit).</p>

<p>The lang option sets the language to a value that is known to be supported by Sybase.  This may not be necessary on all platforms.  See <a href="../faq.html#sqlserver">the FAQ</a> for more info.</p>

<p>See the <a href="configreference.html#sap">SQL Relay Configuration Reference</a> for other valid SAP/Sybase connect string options.</p>

<p>See <a target="_blank" href="http://systems.firstworks.com/p/getting.html">Getting Started With SAP/Sybase</a> for general assistance installing and configuring an SAP/Sybase database.</p>

<br/><a name="db-sapfreetds"/><h4>SAP/Sybase (using FreeTDS)</h4>

<p>While the SAP/Sybase native library can be used to access a SAP/Sybase database on all platforms, on Linux and Unix platforms, access to SAP/Sybase databases is also available using <a target="_blank" href="http://www.freetds.org">FreeTDS</a>.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"freetds"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"server=TESTDB;user=testuser;password=testpassword;db=testdb"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The server option refers to an entry in the freetds.conf file (usually /etc/freetds.conf or /usr/local/etc/freetds.conf) which identifies the database server, similar to:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><font color="#990000">[</font>TESTDB<font color="#990000">]</font>
	host <font color="#990000">=</font> testhost
	port <font color="#990000">=</font> <font color="#993399">5000</font>
	<font color="#008080">tds</font> version <font color="#990000">=</font> <font color="#993399">5.0</font></tt></pre>

</blockquote>
<p>(Note that the freetds.conf file must be readable by the user that the instance of SQL Relay is run as.)</p>

<p>See the <a href="configreference.html#freetds">SQL Relay Configuration Reference</a> for other valid FreeTDS connect string options.</p>

<p>See <a target="_blank" href="http://systems.firstworks.com/p/getting.html">Getting Started With SAP/Sybase</a> for general assistance installing and configuring an SAP/Sybase database.</p>

<br/><a name="db-db2"/><h4>IBM DB2</h4>

<p>In this example, SQL Relay is configured to connect to an IBM DB2 database.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"db2"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"db=testdb;user=db2inst1;password=db2inst1pass;timeout=0"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The db option refers to an entry in the local DB2 instance's database catalog.  See <a target="_blank" href="http://systems.firstworks.com/p/getting-started-with-ibm-db2.html#accessingremote">Getting Started With IBM DB2 - Accessing Remote Instances</a> for more information.</p>

<p>The timeout=0 option tells SQL Relay not to time out when connecting to the database.  DB2 instances can take a long time to log in to sometimes.  The default timeout is often too short.</p>

<p>See the <a href="configreference.html#db2">SQL Relay Configuration Reference</a> for other valid IBM DB2 connect string options.</p>

<p>See <a target="_blank" href="http://systems.firstworks.com/p/getting-started-with-ibm-db2.html">Getting Started With IBM DB2</a> for general assistance installing and configuring an IBM DB2 database.</p>

<br/><a name="db-informix"/><h4>Informix</h4>

<p>In this example, SQL Relay is configured to connect to an Informix database.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"informix"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"informixdir=/opt/informix;servername=ol_informix1210;db=testdb;user=testuser;password=testpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The informixdir option refers to the base directory of the Informix software installation.  On Windows platforms, it should be specified as a Windows-style pathwith doubled backslashes.  For example:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>C<font color="#990000">:\\</font><font color="#008080">Program</font> Files<font color="#990000">\\</font>IBM Informix Software Bundle</tt></pre>

</blockquote>
<p>The informixdir option is often unnecessary, as the $INFORMIXDIR environment variable is usually set system-wide.</p>

<p>On Linux and Unix platforms, the servername option refers to an entry in the sqlhosts file (usually $INFORMIXDIR/etc/sqlhosts) which identifies the database server, similar to:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>ol_informix1210 onsoctcp <font color="#993399">192.168</font><font color="#990000">.</font><font color="#993399">123.59</font> ol_informix1210</tt></pre>

</blockquote>
<p>The second ol_informix1210 in the sqlhosts file refers to an entry in /etc/services which identifies the port that the server is listening on, similar to:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>ol_informix1210 <font color="#993399">29756</font><font color="#990000">/</font>tcp</tt></pre>

</blockquote>
<p>(Note that the sqlhosts and /etc/services files must be readable by the user that the instance of SQL Relay is run as.)</p>

<p>On Windows platforms, the servername option refers to a similar entry created in an opaque location with the Setnet32 program.</p>

<p>See the <a href="configreference.html#informix">SQL Relay Configuration Reference</a> for other valid Informix connect string options.</p>

<br/><a name="db-mysql"/><h4>MySQL</h4>

<p>In this example, SQL Relay is configured to connect to a MySQL database.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"mysql"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=testuser;password=testpassword;host=testhost;db=testdb"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The host and db options indicate that SQL Relay should connect to the database testdb on the host testhost.</p>

<p>See the <a href="configreference.html#mysql">SQL Relay Configuration Reference</a> for other valid MySQL connect string options.</p>

<p>See <a target="_blank" href="http://systems.firstworks.com/p/getting-started-with-mysql.html">Getting Started With MySQL</a> for general assistance installing and configuring a MySQL database.</p>

<br/><a name="db-postgresql"/><h4>PostgreSQL</h4>

<p>In this example, SQL Relay is configured to connect to a PostgreSQL database.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"postgresql"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=testuser;password=testpassword;host=testhost;db=testdb"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The host and db options indicate that SQL Relay should connect to the database testdb on the host testhost.</p>

<p>See the <a href="configreference.html#postgresql">SQL Relay Configuration Reference</a> for other valid PostgreSQL connect string options.</p>

<p>See <a target="_blank" href="http://systems.firstworks.com/p/blog-page_51.html">Getting Started With PostgreSQL</a> for general assistance installing and configuring a PostgreSQL database.</p>

<br/><a name="db-firebird"/><h4>Firebird</h4>

<p>In this example, SQL Relay is configured to connect to a Firebird database.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"firebird"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=testuser;password=testpassword;db=testhost:/opt/firebird/testdb.gdb"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The db option indicates that SQL Relay should connect to the database located at /opt/firebird/testdb.gdb on the host testhost.</p>

<p>Note that if the database is located on a Windows host, then the path segment of the db option should be specified as a Windows-style path with doubled backslashes.  For example:
<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>testhost<font color="#990000">:</font>C<font color="#990000">:\\</font><font color="#008080">Program</font> Files<font color="#990000">\\</font>Firebird<font color="#990000">\\</font>Firebird_3_0<font color="#990000">\\</font>testdb<font color="#990000">.</font>gdb</tt></pre>

</blockquote>
</p>

<p>See the <a href="configreference.html#firebird">SQL Relay Configuration Reference</a> for other valid Firebird connect string options.</p>

<p>See <a target="_blank" href="http://systems.firstworks.com/p/getting-started-with-firebird.html">Getting Started With Firebird</a> for general assistance installing and configuring a Firebird database.</p>

<br/><a name="db-sqlite"/><h4>SQLite</h4>

<p>In this example, SQL Relay is configured to connect to a SQLite database.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"sqlite"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"db=/var/sqlite/testdb"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The db option indicates that SQL Relay should connect to the database /var/sqlite/testdb.</p>

<p>Note that the database file (testdb in this case) and the directory that its located in (/var/sqlite in this case) must both be readable and writable by the user that the instance of SQL Relay is run as.</p>

<p>SQLite also supports a high-performance in-memory mode where tables are maintained in memory and nothing is written to permanent storage.  To use this mode with SQL Relay, set the db option to :memory:.</p>

<p>As each running instance of sqlr-connection will have its own separate in-memory database, you almost certainly want to limit the number of connections to 1.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"sqlite"</font> <font color="#009900">connections</font><font color="#990000">=</font><font color="#FF0000">"1"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"db=:memory:"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>Note that the entire in-memory database will be lost when SQL Relay is stopped.  There is no way to preserve it.  Such is the nature of pure in-memory databases.</p>

<p>See the <a href="configreference.html#sqlite">SQL Relay Configuration Reference</a> for other valid SQLite connect string options.</p>

<p>See <a target="_blank" href="http://systems.firstworks.com/p/getting-started-with-sqlite.html">Getting Started With SQLite</a> for general assistance installing and configuring a SQLite database.</p>

<br/><a name="db-odbc"/><h4>ODBC</h4>

<p>ODBC can be used to access databases for which SQL Relay has no native support.  On Windows platforms, ODBC is commonly used to access Microsoft SQL Server and Microsoft Access databases.  On Linux platforms, the <a target="_blank" href="https://msdn.microsoft.com/en-us/library/hh568451(v=sql.110).aspx">Microsoft-provided ODBC driver</a> is also commonly used to access Microsoft SQL Server databases, as an alternative to <a target="_blank" href="http://www.freetds.org">FreeTDS</a>.</p>

<p>In this example, SQL Relay is configured to connect to a ODBC database.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"odbc"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"dsn=testdsn"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The dsn option refers to an ODBC DSN (Data Source Name).</p>

<p>On Linux and Unix platforms, the DSN is an entry in the odbc.ini file (usually /etc/odbc.ini) which identifies the database server, similar to:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><font color="#990000">[</font>testdsn<font color="#990000">]</font>
Description<font color="#990000">=</font>SQL Server
Driver<font color="#990000">=</font>ODBC Driver <font color="#993399">11</font> <b><font color="#0000FF">for</font></b> SQL Server
Server<font color="#990000">=</font>testhost
Port<font color="#990000">=</font><font color="#993399">1433</font>
Database<font color="#990000">=</font>
User<font color="#990000">=</font>testuser
Password<font color="#990000">=</font>testpassword</tt></pre>

</blockquote>
<p>The Driver parameter refers to an entry in the odbcinst.ini file (usually /etc/odbcinst.ini) which identifies driver files:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><font color="#990000">[</font>ODBC Driver <font color="#993399">11</font> <b><font color="#0000FF">for</font></b> <font color="#008080">SQL</font> Server<font color="#990000">]</font> 
Description<font color="#990000">=</font>Microsoft ODBC Driver <font color="#993399">11</font> <b><font color="#0000FF">for</font></b> SQL Server
Driver<font color="#990000">=/</font>opt<font color="#990000">/</font>microsoft<font color="#990000">/</font>msodbcsql<font color="#990000">/</font>lib64<font color="#990000">/</font>libmsodbcsql<font color="#990000">-</font><font color="#993399">11.0</font><font color="#990000">.</font>so<font color="#990000">.</font><font color="#993399">2270.0</font> 
Threading<font color="#990000">=</font><font color="#993399">1</font> 
UsageCount<font color="#990000">=</font><font color="#993399">1</font> </tt></pre>

</blockquote>
<p>(Note that the odbc.ini and odbcinst.ini files must be readable by the user that the instance of SQL Relay is run as.)</p>

<p>On Windows platforms, the DSN is an entry in the Windows Registry, created by the ODBC Data Source Administrator (odbcad32.exe).</p>

<p>See the <a href="configreference.html#odbc">SQL Relay Configuration Reference</a> for other valid ODBC connect string options.</p>

<p>See <a target="_blank" href="http://systems.firstworks.com/p/blog-page_65.html">Getting Started With ODBC (on a non-MS platform)</a> for general assistance installing and configuring ODBC on a non-MS platform.</p>

<br/><a name="db-msaccess"/><h4>Microsoft Access (using MDBTools)</h4>

<p>On Windows platforms, ODBC can be used to access a Microsoft Access database.</p>

<p>On Linux and Unix platforms, limited read-only access to Microsoft Access databases is available using <a target="_blank" href="http://mdbtools.sourceforge.net">MDBTools</a>.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"mdbtools"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"db=/var/mdbtools/testdb.mdb"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The db option indicates that SQL Relay should connect to the database /var/mdbtools/testdb.mdb.</p>

<p>(Note that the database file must be readable by the user that the instance of SQL Relay is run as.)</p>

<p>See the <a href="configreference.html#mdbtools">SQL Relay Configuration Reference</a> for other valid MDBTools connect string options.</p>

<p>See <a target="_blank" href="http://systems.firstworks.com/p/blog-page_8.html">Getting Started With MS Access (on a non-MS platform)</a> for general assistance with MS Access databases on non-MS platforms.</p>

<br/><a name="instances"/><h3>Multiple Instances</h3>

<p>Any number of SQL Relay instances can be defined in the configuration file.</p>

<p>In following example, instances that connect to Oracle, SAP/Sybase and DB2 are defined in the same file.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"oracleexample"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">"9000"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"sapexample"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"sap"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">"9001"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"sybase=/opt/sap;lang=en_US;server=TESTDB;user=testuser;password=testpassword;db=testdb"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"db2example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"db2"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">"9002"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"db=testdb;user=db2inst1;password=db2inst1pass;lang=C;timeout=0"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>These instances can be started using:</p>

<blockquote>
  <pre>sqlr-start -id oracleexample
sqlr-start -id sapexample
sqlr-start -id db2example
</pre>

</blockquote>
<blockquote>
( <b>NOTE:</b> When installed from RPM packages, SQL Relay may have to be started and stopped as root.)
</blockquote>
<p>...and accessed using:</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver -port 9000
sqlrsh -host sqlrserver -port 9001
sqlrsh -host sqlrserver -port 9002
</pre>

</blockquote>
<br/><a name="autostart"/><h3>Starting Instances Automatically</h3>

<p>In all previous examples sqlr-start has been called with the -id option, specifying which instance to start.  If sqlr-start is called without the -id option then it will start all instances configured with the enabled attribute set to yes.</p>

<p>For example, if the following instances are defined...</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"oracleexample"</font> <font color="#009900">enabled</font><font color="#990000">=</font><font color="#FF0000">"yes"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">"9000"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"sapexample"</font> <font color="#009900">enabled</font><font color="#990000">=</font><font color="#FF0000">"yes"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"sap"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">"9001"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"sybase=/opt/sap;lang=en_US;server=TESTDB;user=testuser;password=testpassword;db=testdb"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"db2example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"db2"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">"9002"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"db=testdb;user=db2inst1;password=db2inst1pass;lang=C;timeout=0"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>...then calling sqlr-start without the -id parameter will start oracleexample and sapexample because enabled="yes" is configured for those instances.  db2example will not be started because enabled="yes" is not configured for that instance.</p>

<p>When installed on most platforms, SQL Relay creates a systemd service file (usually in /usr/lib/systemd/system or /lib/systemd/system) or an init script in the appropriate place under /etc.  These call sqlr-start with no -id option.  If configured to run at boot, they will start all instances for which enabled="yes" is configured.</p>

<p>How to enable the service file or init script depends on what platform you are using.</p>

<p>On systemd-enabled Linux, this usually involves running:</p>

<blockquote>
systemctl enable sqlrelay.service
</blockquote>
<p>On non-systemd-enabled Linux, Solaris, SCO and other non-BSD Unixes, this usually involves creating a symlink from /etc/init.d/sqlrelay to /etc/rc3.d/S85sqlrelay.  This can be done manually, but most platforms provide utilities to do it for you.</p>

<p>Redhat-derived Linux distributions have a chkconfig command that can do this for you:</p>

<blockquote>
chkconfig --add sqlrelay
</blockquote>
<p>Debian-derived Linux distributions provide the update-rc.d command:</p>

<blockquote>
update-rc.d sqlrelay defaults
</blockquote>
<p>Solaris provides svcadm:</p>

<blockquote>
svcadm enable sqlrelay
</blockquote>
<p>On FreeBSD you must add a line to /etc/rc.conf like:</p>

<blockquote>
sqlrelay_enabled=YES
</blockquote>
<p>On NetBSD you must add a line to /etc/rc.conf like:</p>

<blockquote>
sqlrelay=YES
</blockquote>
<p>On OpenBSD you must add a line to /etc/rc.conf like:</p>

<blockquote>
sqlrelay_flags=""
</blockquote>
<hr/>

<br/><a name="altconfigfile"/><h2>Alternate Configuration File Options</h2>

<a name="directory"/><h3>Configuration Directory</h3>

<p>While any number of SQL Relay instances can be defined in a single configuration file, it might be more convenient to split configurations up into multiple files located in a configuration directory.</p>

<p>The default SQL Relay configuration directory depends on the platform and on how you installed SQL Relay.</p>

<ul>
  <li>Unix and Linux</li>
  <ul>
    <li>Built from source - <b>/usr/local/firstworks/etc/sqlrelay.conf.d</b> (unless you specified a non-standard --prefix or --sysconfdir during the build)</li>
    <li>RPM package - <b>/etc/sqlrelay.conf.d</b></li>
    <li>FreeBSD package - <b>/usr/local/etc/sqlrelay.conf.d</b></li>
    <li>NetBSD package - <b>/usr/pkg/etc/sqlrelay.conf.d</b></li>
    <li>OpenBSD package - <b>/usr/local/etc/sqlrelay.conf.d</b></li>
  </ul>

  <li>Windows</li>
  <ul>
    <li>Built from source - <b>C:\Program Files\Firstworks\etc\sqlrelay.conf.d</b></li>
    <li>Windows Installer package - <b>C:\Program Files\Firstworks\etc\sqlrelay.conf.d</b> (unless you specified a non-standard installation folder)</li>
  </ul>

</ul>

<p>Additional configuration files may be created under this directory.  These files must follow the same format as the main configuration file.</p>

<p>For example, if you wanted to split up oracle, sap and db2 configurations into 3 separate files, you could create:</p>

<p><b>sqlrelay.conf.d/oracle.conf</b></p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"oracleexample"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">"9000"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p><b>sqlrelay.conf.d/sap.conf</b></p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"sapexample"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"sap"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">"9001"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"sybase=/opt/sap;lang=en_US;server=TESTDB;user=testuser;password=testpassword;db=testdb"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p><b>sqlrelay.conf.d/db2.conf</b></p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"db2example"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"db2"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">"9002"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"db=testdb;user=db2inst1;password=db2inst1pass;lang=C;timeout=0"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<br/><br/><a name="specifying"/><h3>Specifying Configuration Files</h3>

<p>It is also possible to specify a particular configuration file or directory by passing the sqlr-start program a -config option.</p>

<p>For example:</p>

<blockquote>
  <pre>sqlr-start -id oracleexample -config /home/myuser/sqlrelay.conf
sqlr-start -id oracleexample -config file:///home/myuser/sqlrelay.conf
sqlr-start -id oracleexample -config dir:///home/myuser/sqlrelay.conf.d
</pre>

</blockquote>
<blockquote>
( <b>NOTE:</b> When installed from RPM packages, SQL Relay may have to be started and stopped as root.)
</blockquote>
<p>(the file:// prefix is optional when specifying a file, but the dir:// prefix must be included when specifying a directory)</p>

<p>The -config option may also be used to specify a comma-separated list of files or directories.</p>

<p>For example:</p>

<blockquote>
  <pre>sqlr-start -id oracleexample -config /home/myuser/sqlrelay-1.conf,/home/myuser/sqlrelay-2.conf
sqlr-start -id oracleexample -config /home/myuser/sqlrelay-1.conf,/home/myuser/sqlrelay-2.conf,dir:///home/myuser/sqlrelay.conf.d
sqlr-start -id oracleexample -config /home/myuser/sqlrelay-1.conf,/home/myuser/sqlrelay-2.conf,dir:///home/myuser/sqlrelay-1.conf.d,dir:///home/myuser/sqlrelay-2.conf.d
</pre>

</blockquote>
<blockquote>
( <b>NOTE:</b> When installed from RPM packages, SQL Relay may have to be started and stopped as root.)
</blockquote>
<p>Files and directories are processed in the order that they are specified.</p>

<br/><a name="remote"/><h3>Remote Configuration Files</h3>

<p>In addition to local configuration files, the -config option may also be used to specify configuration files located on a remote host, accessible via http.</p>

<p>Actually, if the Rudiments library upon which SQL Relay depends was compiled with support for libcurl, then configuration files may also be remotely accessible over other protocols supported by libcurl, such as https, ftp, scp, sftp, smb, etc.</p>

<p>For example:</p>

<blockquote>
  <pre>sqlr-start -id oracleexample -config http://configserver.mydomain.com/sqlrconfig/sqlrelay.conf
sqlr-start -id oracleexample -config http://myuser:mypassword@configserver.mydomain.com/sqlrconfig/sqlrelay.conf
sqlr-start -id oracleexample -config http://[/usr/local/firstworks/etc/sqlruserpwd.txt]@configserver.mydomain.com/sqlrconfig/sqlrelay.conf

sqlr-start -id oracleexample -config https://configserver.mydomain.com/sqlrconfig/sqlrelay.conf
sqlr-start -id oracleexample -config https://myuser:mypassword@configserver.mydomain.com/sqlrconfig/sqlrelay.conf
sqlr-start -id oracleexample -config https://[/usr/local/firstworks/etc/sqlruserpwd.txt]@configserver.mydomain.com/sqlrconfig/sqlrelay.conf

sqlr-start -id oracleexample -config scp://myuser:mypassword@configserver.mydomain.com/usr/local/firstworks/etc/sqlrelay.conf
sqlr-start -id oracleexample -config scp://[/usr/local/firstworks/etc/sqlruserpwd.txt]@configserver.mydomain.com/usr/local/firstworks/etc/sqlrelay.conf
</pre>

</blockquote>
<blockquote>
( <b>NOTE:</b> When installed from RPM packages, SQL Relay may have to be started and stopped as root.)
<br/><br/>
( <b>NOTE:</b> The https and scp examples only work if Rudiments was compiled with support for libcurl.)
</blockquote>
<p>In some of the examples above, a user and password are given in the url, separated by a colon, prior to the @ sign.  In other examples, in place of a literal user and password, a user-password file is specified in square brackets.  If a user-password file is used, then the file should contain a single line, consisting of colon-separated user and password.</p>

<p>For example:</p>

<blockquote>
  <pre>myuser:mypassword
</pre>

</blockquote>
<p>Password protection is recommended for remotely accessible configuration files as they may contain users and passwords for accessing the database and SQL Relay itself.</p>

<p>Using user-password files is recommended over passing literal users and passwords.  The files can be protected with file permissions, they prevent the user and password from being stored in the script that starts SQL Relay, and they prevent the user and password from being displayed in a process listing.</p>

<br/><a name="linkfiles"/><h3>Link Files</h3>

<p>So far, the example configuration files have all been XML files, containing configurations for instances of SQL Relay.</p>

<p>However, a configuration file can, alternatively, be a "link file", containing nothing but links to other configuration files.</p>

<p>For example:</p>

<blockquote>
  <pre># oracle configuration
http://myuser:mypassword@configserver.mydomain.com/sqlrconfig/oracle.conf

# sap/sybase configuration
http://myuser:mypassword@configserver.mydomain.com/sqlrconfig/sap.conf

# db2 configuration
http://myuser:mypassword@configserver.mydomain.com/sqlrconfig/db2.conf
</pre>

</blockquote>
<p>Lines starting with # are considered to be comments and blank lines are ignored, but every other line is interpreted as the location of a local configuration file, local configuration directory, or remote configuration file, as described in the previous sections.</p>

<p>Each of these files or directories are processed in the order that they are specified.</p>

<p>Link files can be used to centralize configuration.  For example, if you have several SQL Relay servers, rather than distributing configuration files across the servers, you could create an identical sqlrelay.conf file on each of them like:</p>

<blockquote>
  <pre>http://myuser:mypassword@configserver.mydomain.com/sqlrconfig/sqlrelay.conf
</pre>

</blockquote>
<p>And then, on configserver.mydomain.com, host an sqlrelay.conf file like:</p>

<blockquote>
  <pre>http://myuser:mypassword@configserver.mydomain.com/sqlrconfig/oracle.conf
http://myuser:mypassword@configserver.mydomain.com/sqlrconfig/sap.conf
http://myuser:mypassword@configserver.mydomain.com/sqlrconfig/db2.conf
</pre>

</blockquote>
<p>The files oracle.conf, sap.conf, and db2.conf could then be hosted by and maintained on that server as well.</p>

<p>The links in these examples are all urls, but they could just as easily be links to local files and directories as well.  It is important to note though, that SQL Relay interprets all local file and directory locations relative to the local machine.  If a remotely hosted link file contains a reference to a local file or directory, then SQL Relay will look for that file on the local machine, not the remote machine.</p>

<p>Similarly, urls are resolved using the DNS configuration of the local machine as well, not the DNS configuration of the remote machine.</p>

<p>The urls in these examples all contain literal users and passwords.  User-password files can also be used as described in the section <a href="#remote">Remote Configuration Files</a>.  However, the user-password file must exist at the specified location on the local machine.</p>

<p>As link files can be protected by file permissions, and the urls stored in them aren't exposed anywhere else, such as in a process listing, user-password files are not generally necessary when using link files.</p>

<p>There is no limit to the depth of links.  A link file can reference another link file which references another, which references another, etc.  Too great a depth could lead to slow startup times though, especially when using remote configration files. This is especially significant when using <a href="#dynamicscaling">Dynamic Scaling</a>, as the configuration must be loaded each time a new connection is spawned.  Care should also be taken to avoid loops.</p>

<hr/>

<br/><a name="ha"/><h2>High Availabiltiy</h2>

<p>In a high availability environment, SQL Relay can be deployed as a front-end to provide load-balancing and fail-over for a set of replicated database servers or database cluster.  Load-balancing and fail-over can also be implemented over multiple SQL Relay servers.</p>

<br/><a name="cluster"/><h3>Load-Balancing and Fail-Over With Replicated Databases or Database Clusters</h3>

<p>In a database cluster or replication environment, SQL Relay can be configured to maintain a pool of connections to the various database nodes and distribute client sessions over the nodes.  If an individual node fails, SQL Relay will attempt to reestablish connections to that node, while continuing to distribute client sessions over the remaining nodes.</p>

<table>
  <tr>
    <td><img src="../images/cluster.png"/>
</td>
    <td><img style="padding-left: 40px; " src="../images/replicated.png"/>
</td>
  </tr>
</table>

<p>In the configuration file, each connection tag defines a node to maintain connections to.  In the following example, SQL Relay is configured to distribute over three Oracle nodes - orcl1, orcl2, and orcl3</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl1"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl2"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl3"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>Any number of connection tags may be defined.</p>

<p>SQL Relay also supports disproportionate distribution of load. If some nodes can handle more traffic than others, then SQL Relay can be configured to send more traffic to the more capable nodes.</p>

<p><img src="../images/replicated-disproportionate.png"/></p>

<p>SQL Relay uses the connection tag's metric attribute to decide how many connections to open to each node.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl1"</font> <font color="#009900">metric</font><font color="#990000">=</font><font color="#FF0000">"5"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl2"</font> <font color="#009900">metric</font><font color="#990000">=</font><font color="#FF0000">"15"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl3"</font> <font color="#009900">metric</font><font color="#990000">=</font><font color="#FF0000">"30"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The metric attribute doesn't specify the number of connections to open to each node, but the higher the metric relative to the other metrics, the more connections to that node will be opened and maintained.  For example, if the metric for the first node is twice as large as the metric for the second node, then SQL Relay will open twice as many connections to the first node as the second.</p>

<p>In the example above, 15 is 3 times 5, so 3 times as many connections will be opened to orcl2 as to orcl1.  30 is 6 times 5, so 6 times as many connections will be opened to orcl3 as orcl1.  Since a total of 10 connections will be opened, 1 will be opened to orcl1, 3 to orcl2, and 6 to orcl2.</p>

<br/><a name="rac"/><h3>Already-Load-Balanced Databases</h3>

<p>In a typical database cluster or replicated environment, the nodes are identifiable as separate hosts.  However, when the nodes are located behind a load-balancing appliance or running on an application cluster, such as Oracle RAC, SQL Relay cannot identity an individual node.</p>

<p>In these environments, if a node goes down, SQL Relay will attempt to re-establish the connection, but rather than failing until the node comes back up, the new connection will more likely just succeed to a different node in the cluster.  Over time, this can lead to disproportionate load-balancing, with a bias toward nodes that have never gone down.</p>

<p>SQL Relay manages this by "shuffling" the connections periodically.  Every so often, each database connection is re-established, giving that connection a chance to be re-established to a node that may have gone down but is now back up.</p>

<p>To indicate to SQL Relay that the nodes are already-load-balanced, and need to be "shuffled" periodically, only one connection tag should be used, with the behindloadbalancer attribute set to "yes".</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orclrac"</font> <font color="#009900">behindloadbalancer</font><font color="#990000">=</font><font color="#FF0000">"yes"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<br/><br/><a name="masterslave"/><h3>Master-Slave Query Routing</h3>

<p>The load-balancing scenarios described above all assume that master-master replication is being used.  SQL Relay supports master-slave replication as well.</p>

<p>In a master-slave replication environment, SQL Relay can be configured to route DML and DDL queries to the master and distribute selects over the slaves.</p>

<p><img src="../images/router.png"/></p>

<p>This actually requires 3 instances of SQL Relay.  One to connect to the master, one to connect to the slaves, and a third to route queries to the first two.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

        <i><font color="#9A1900">&lt;!-- This instance maintains connections to the "master" MySQL database</font></i>
<i><font color="#9A1900">                on the masterdb machine.  This instance only listens on the</font></i>
<i><font color="#9A1900">                unix socket /tmp/master.socket and thus cannot be connected to</font></i>
<i><font color="#9A1900">                by clients from another machine. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"master"</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/master.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"mysql"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"masteruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"masterpassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
                <b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=masteruser;password=masterpassword;host=masterdb;db=master;"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>


        <i><font color="#9A1900">&lt;!-- This instance maintains connections to 4 "slave" MySQL databases</font></i>
<i><font color="#9A1900">                on 4 slave machines.  This instance only listens on the unix</font></i>
<i><font color="#9A1900">                socket /tmp/slave.socket and thus cannot be connected to by</font></i>
<i><font color="#9A1900">                clients from another machine. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"slave"</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/slave.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"mysql"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"slaveuser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"slavepassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
                <b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=slaveuser;password=slavepassword;host=slavedb1;db=slave;"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=slaveuser;password=slavepassword;host=slavedb2;db=slave;"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=slaveuser;password=slavepassword;host=slavedb3;db=slave;"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=slaveuser;password=slavepassword;host=slavedb3;db=slave;"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>


        <i><font color="#9A1900">&lt;!-- This instance sends DML (insert,update,delete) and</font></i>
<i><font color="#9A1900">                DDL (create/delete) queries to the "master" SQL Relay instance</font></i>
<i><font color="#9A1900">                which, in turn, sends them to the "master" database.</font></i>
<i><font color="#9A1900">                This instance sends any other queries to the "slave" SQL Relay</font></i>
<i><font color="#9A1900">                instance which, in turn, distributes them over the "slave"</font></i>
<i><font color="#9A1900">                databases. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"router"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"router"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"routeruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"routerpassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;routers&gt;</font></b>
                        <i><font color="#9A1900">&lt;!-- send all DML/DDL queries to "master"  --&gt;</font></i>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"master"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^drop "</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^create "</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^insert "</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^update "</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^delete "</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
                        <i><font color="#9A1900">&lt;!-- send all other queries to "slave" --&gt;</font></i>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"slave"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">".*"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
		<b><font color="#0000FF">&lt;/routers&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"master"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/master.socket;user=masteruser;password=masterpassword"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"slave"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/slave.socket;user=slaveuser;password=slavepassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The first two instances use familiar configuration options, but the third uses a dbtype of "router" and uses router tags to define query routing rules.</p>

<p>(Note the <i>module</i> attribute of the router tag.  SQL Relay is highly modular, and many advanced features, including query routing, are implemented by loadable modules.)</p>

<p>(Note also the use of a notifications tag.  See <a href="#notifications">Notifications</a> below for more information.)</p>

<p>Each router tag defines a connectionid to send the query to and a set of regular expression patterns to match.  Queries that match the set of patterns defined in the pattern tags are sent to the instance of SQL Relay designated by the connectionid in the router tag.</p>

<p>The three instances can be started using:</p>

<blockquote>
  <pre>sqlr-start -id master
sqlr-start -id slave
sqlr-start -id router
</pre>

</blockquote>
<blockquote>
( <b>NOTE:</b> When installed from RPM packages, SQL Relay may have to be started and stopped as root.)
</blockquote>
<p>Client applications should connect to the router instance rather than the master or slave instances.</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver -user routeruser -password routerpassword
</pre>

</blockquote>
<br/><br/><a name="frontend"/><h3>Front-End Load-Balancing and Fail-Over</h3>

<p>If you are building out a high availability environment, or if your pool of application servers is just sufficiently large, you might want to set up a pool of SQL Relay servers between your application servers and the database.</p>

<p>SQL Relay supports two front-end load-balancing and fail-over strategies.  In the first strategy, load-balancing and fail-over are provided by an appliance or application cluster.  In the second, SQL Relay provides its own load-balancing and fail-over, with some help from DNS.</p>

<p>Multiple instances of SQL Relay can be placed behind a load-balancing appliance.</p>

<p><img src="../images/loadbalancer.png"/></p>

<p>In this illustration, the load-balancing appliance is shown as a single machine, but in a true HA environment, there would be 2 or more appliances sharing a virtual IP.  Alternatively, rather than using an appliance, SQL Relay can be run on an application server cluster such as Linux Virtual Server.</p>

<p><a target="_blank" href="http://en.wikipedia.org/wiki/Round-robin_DNS">Round-robin DNS</a> can be also be used to provide load-balancing and fail-over over multiple SQL Relay servers.</p>

<p><img src="../images/rrdns.png"/></p>

<p>In a round-robin DNS scenario, multiple IP addresses are assigned to the same host name.  The SQL Relay client is then configured to connect to that host.  When it requests the IP addresses for the host, the client receives all of the IP addresses assigned to it, rather than just a single address.</p>

<p>Round-robin DNS is so-called because, traditionally, the order of the IP addresses returned on successive requests alternated reliably, in round-robin fashion.  This behavior persists in many environments, but it is no longer guaranteed, as many modern DNS resolvers sort the list and return the IP addresses in the same order, every time.  SQL Relay clients randomize the list though, and try to connect to each of the IP addresses, one-at-a-time, until they succeed.  Doing so provides both load-balancing and fail-over without requiring an appliance or application server cluster.</p>

<hr/>

<br/><a name="authoptions"/><h2>Authentication/Authorization Options</h2>

<p>There are several options for controlling which users are allowed to access an instance of SQL Relay.</p>

<a name="userlistauth"/><h3>User List Auth</h3>

<p>The standard authentication/authorization option is <i>user list</i> auth.</p>

<p>When user list auth is used, a user is authenticated/authorized against a static list of valid user/password combinations.  This is the method used in all of the examples above.</p>

<p>To enable user list auth, you must provide a list of valid user/password combinations, as follows:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>
	...
	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> ... <b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"user1"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"password1"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"user2"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"password2"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"user2"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"password2"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>
	...
<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<br/><a name="dbauth"/><h3>Database Auth</h3>

<p>Another authentication/authorization option is <i>database</i> auth.</p>

<p>When database auth is used, a user is authenticated/authorized against the database itself.  SQL Relay does this by checking the provided credentials against the credentials that are currently in use.  If they differ, then it logs out of the database and logs back in using the provided credentials.</p>

<p>To enable database auth, omit the list of user/passwords and configure authtier="database" as follows.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>
	...
	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> ... <font color="#009900">authtier</font><font color="#990000">=</font><font color="#FF0000">"database"</font> ... <b><font color="#0000FF">&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>
	...
<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<blockquote>
( <b>NOTE:</b> Database auth should not be used in an instance where dbase="router".  It's OK for the instances that the router routes to to use it, but the router instance itself should not.  If database auth is used for that instance, then auth will fail.)
<br/><br/>
( <b>NOTE:</b> Prior to version 0.65.0, the "database" auth method defaulted to the behavior of the "proxied" auth method and fell back to the current behavior if the proxied behavior was unsupported.  There was no way to force this behavior.  As of 0.65.0 the funcationality is split into two separate modules.)
</blockquote>
<br/><a name="proxiedauth"/><h3>Proxied Auth</h3>

<p>Another authentication/authorization option is <i>proxied</i> auth.</p>

<p>When proxied auth is used, a user is authenticated/authorized against the database itself, though in a different manner than datbase auth described above.  SQL Relay logs into the database as a user with permissions to proxy other users.  For each client session, SQL Relay checks the provided credentials against the credentials that are currently in use.  If they differ, then it asks the proxy user to switch the user it's proxying to the provided user.</p>

<p>This is currently only supported with Oracle (version 8i or higher) and requires database configuration.  See <a href="oraclentier.html">this document</a> for more information including instructions for configuring Oracle.</p>

<p>To enable proxied auth, omit the list of user/passwords and configure authtier="proxied" as follows.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>
	...
	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> ... <font color="#009900">authtier</font><font color="#990000">=</font><font color="#FF0000">"proxied"</font> ... <b><font color="#0000FF">&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>
	...
<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<blockquote>
( <b>NOTE:</b> Proxied auth should not be used in an instance where dbase="router".  It's OK for the instances that the router routes to to use it, but the router instance itself should not.  If proxied auth is used for that instance, then auth will fail.)
</blockquote>
<br/><a name="krb"/><h3>Kerberos and Active Directory Encryption and Authentication</h3>

<p>SQL Relay supports Kerberos encryption and authentication.</p>

<p>When Kerberos encryption and authentication is used:</p>

<ul>
  <li>All communications between the SQL Relay client and SQL Relay server are encrypted.</li>
  <li>A user who has authenticated against a Kerberos KDC or Active Directory Domain Controller can access SQL Relay without having to provide additional credentials.</li>
</ul>

<p>On Linux and Unix systems, both server and client environments must be "Kerberized".  On Windows systems, both server and client must join an Active Directory Domain.  Note that this is only available on Professional or Server versions of Windows.  Home versions cannot join Active Directory Domains.</p>

<p>The following configuration configures an instance of SQL Relay to use Kerberos authentication and encryption:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">krb</font><font color="#990000">=</font><font color="#FF0000">"yes"</font> <font color="#009900">krbservice</font><font color="#990000">=</font><font color="#FF0000">"sqlrelay"</font> <font color="#009900">krbkeytab</font><font color="#990000">=</font><font color="#FF0000">"/usr/local/firstworks/etc/sqlrelay.keytab"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"dmuse@KRB.FIRSTWORKS.COM"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"kmuse@KRB.FIRSTWORKS.COM"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"imuse@KRB.FIRSTWORKS.COM"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"smuse@KRB.FIRSTWORKS.COM"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"FIRSTWORKS.COM\dmuse"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"FIRSTWORKS.COM\kmuse"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"FIRSTWORKS.COM\imuse"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"FIRSTWORKS.COM\smuse"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<ul>
  <li>The <b>krb</b> parameter enables (or disables) Kerberos authentication and encryption.</li>
  <li>The <b>krbservice</b> parameter specifies which Kerberos service to use.  This parameter is optional and defaults to "sqlrelay".  It is only shown here for illustrative purposes.</li>
  <li>The <b>krbkeytab</b> parameter specifies the location of the keytab file containing the key for the specified Kerberos service.  This parameter is not required on Windows.  On Linux or Unix systems if this paramter is omitted, then it defaults to the system keytab, usually /etc/krb5.keytab</li>
  <li>User list auth is also used.  Database and proxied auth are not currently supported with Kerberos.</li>
</ul>

<p>Note that no passwords are required in the user list.  Note also that users are specified in both user@REALM (Kerberos) format and REALM\user (Active Directory) format to support users authenticated against both systems.</p>

<p>To start the instance on a Linux or Unix system, you must be logged in as a user that can read the file specified by the krbkeytab parameter.</p>

<p>To start the instance on a Windows system, you must be logged in as a user that can proxy the service specified by the krbservice parameter (or it's default value of "sqlrelay" if omitted).</p>

<p>If those criteria are met, starting the Kerberized instance of SQL Relay is the same as starting any other instance:</p>

<blockquote>
  <pre>sqlr-start -id example
</pre>

</blockquote>
<blockquote>
( <b>NOTE:</b> When installed from RPM packages, SQL Relay may have to be started and stopped as root.)
</blockquote>
<p>To access the instance, you must acquire a Kerberos ticket-granting ticket.  On a Linux or Unix system, this typically involves running <i>kinit</i>, though a fully Kerberized environment may acquire this during login.  On a Windows system, you must log in as an Active Directory domain user.</p>

<p>After acquiring the ticket-granting ticket, the instance of SQL Relay may be accessed from a Linux or Unix system as follows:</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver -krb
</pre>

</blockquote>
<p>From a Windows system, it may be necessary to specify the fully qualified Kerberos service name as well:</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver -krb -krbservice sqlrelay/sqlrserver.firstworks.com@AD.FIRSTWORKS.COM
</pre>

</blockquote>
<p>Note the absence of user and password parameters.</p>

<p>Kerberos authentication establishes trust between the user who acquired the ticket-granting ticket (the user running the client program) and the service (the SQL Relay server) as follows:</p>

<ul>
  <li>The client program uses the user's ticket-granting ticket to acquire a ticket for the sqlrelay service.</li>
  <li>The client program then uses this service ticket to establish a security context with the SQL Relay server.</li>
  <li>During this process the client program sends the SQL Relay server the user name that was used to acquire the original ticket-granting ticket.</li>
  <li>If the security context can be successfully established, then the SQL Relay server can trust that the client program is being run by the user that it says it is.</li>
</ul>

<p>Once the SQL Relay server trusts that the client is being run by the user that it says it is, the user is authorized against the list of valid users.</p>

<p>While Kerberos authenticated and encrypted sessions are substantially more secure than standard SQL Relay sessions, several factors contribute to a performance penalty:</p>

<ul>
  <li>The client program may have to acquire a service ticket from another server (the Kerberos KDC or Active Directory Domain Controller) prior to connecting to the SQL Relay server.</li>
  <li>When establishing the secure session, a significant amount of data must be sent back and forth between the client and server over multiple network round-trips.</li>
  <li>Kerberos imposes a limit on the amount of data that can be sent or received at once, so more round trips may be required when processing queries.</li>
  <li>Without dedicated encryption hardware and a Kerberos implementation that supports it, the computation involved in encrypting and decrypting data can also introduce delays.</li>
</ul>

<p>Any kind of full SQL Relay session encryption should be used with caution in performance-sensitive applications.</p>

<br/><a name="tls"/><h3>TLS/SSL Encryption and Authentication</h3>

<p>SQL Relay supports TLS/SSL encryption and authentication.</p>

<p>When TLS/SSL encryption and authentication is used:</p>

<ul>
  <li>All communications between the SQL Relay client and SQL Relay server are encrypted.</li>
  <li>SQL Relay clients and servers may optionally validate each other's certificates and identities.</li>
</ul>

<p>When using TLS/SSL encryption and authentication, at minimum, a certificate must be supplied to the SQL Relay server.  For highly secure production environments, this certificate should come from a trusted certificate authority.  In other environments the certificate may be self-signed, or even be borrowed from another server.</p>

<p>The following configuration enables TLS/SSL security for an instance of SQL relay:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> <font color="#009900">tls</font><font color="#990000">=</font><font color="#FF0000">"yes"</font> <font color="#009900">tlscert</font><font color="#990000">=</font><font color="#FF0000">"/usr/local/firstworks/etc/sqlrserver.pem"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<ul>
  <li>The <b>tls</b> parameter enables (or disables) TLS/SSL encryption.</li>
  <li>The <b>tlscert</b> parameter specifies the TLS/SSL certificate chain to use. (See <a href="tlscert.html">The tlscert Parameter</a> for details)</li>
  <li>User list auth is also used.  Database and proxied auth are not currently supported with TLS/SSL.</li>
</ul>

<p>To start the instance on a Linux or Unix system, you must be logged in as a user that can read the file specified by the tlscert parameter.  If that criterium is met then the instance can be started using:</p>

<blockquote>
  <pre>sqlr-start -id example
</pre>

</blockquote>
<blockquote>
( <b>NOTE:</b> When installed from RPM packages, SQL Relay may have to be started and stopped as root.)
</blockquote>
<p>The instance may be accessed as follows:</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver -user sqlruser -password sqlrpassword -tls -tlsvalidate no
</pre>

</blockquote>
<p>This establishes a TLS/SSL-encrypted session but does not validate the server's certificate or identity.  The session will only continue if the server's certificate is is well-formed and hasn't expired, <b>but the client is still vulnerable to various attacks</b>.</p>

<br/><p>For a more secure session, the client may validate that the server's certificate was signed by a trusted certificate authority, known to the system, as follows:</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver -user sqlruser -password sqlrpassword -tls -tlsvalidate ca
</pre>

</blockquote>
<p>If the server's certificate is self-signed, then the certificate authority won't be known to the system, but it's certificate may be specified by the tlsca parameter as follows:</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver -user sqlruser -password sqlrpassword -tls -tlsvalidate ca -tlsca /usr/local/firstworks/etc/myca.pem
</pre>

</blockquote>
<p>(.pem files are specified in this example, but on Windows systems, .pfx file or Windows Certificate Store references must be used.  See <a href="tlsca.html">The tlsca Parameter</a> for details.)</p>

<p>This establishes a TLS/SSL-encrypted session with the server and validates the server's certificate, but does not validate the server's identity.  The session will only continue if the server's certificate is valid, <b>but the client is still vulnerable to various attacks</b>.</p>

<br/><p>For a more secure session, the client may validate that the host name provided by the server's certificate matches the host name that the client meant to connect to, as follows:</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver.firstworks.com -user sqlruser -password sqlrpassword -tls -tlsvalidate ca+host -tlsca /usr/local/firstworks/etc/myca.pem
</pre>

</blockquote>
<p>(.pem files are specified in this example, but on Windows systems, .pfx file or Windows Certificate Store references must be used.  See <a href="tlsca.html">The tlsca Parameter</a> for details.)</p>

<p>Note that the fully qualified host name was provided.  Note also the use of the ca+host value for the tlsvalidate parameter.  With these parameters, in addition to validating that the server's certificate was signed by a trusted certificate authority, the host name will also be validated.  If the certificate contains Subject Alternative Names, then the host name will be compared to each of them.  If no Subject Alternative Names are provided then the host name will be compared to the certificate's Common Name.  The session will only continue if the sever's certificate and identity are both valid.</p>

<br/><p>Unless self-signed, certificates can be expensive, so certificates are often shared by multiple servers across a domain.  To manage environments like this, the host name validation can be relaxed as follows:</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver.firstworks.com -user sqlruser -password sqlrpassword -tls -tlsvalidate ca+domain -tlsca /usr/local/firstworks/etc/myca.pem
</pre>

</blockquote>
<p>(.pem files are specified in this example, but on Windows systems, .pfx file or Windows Certificate Store references must be used.  See <a href="tlsca.html">The tlsca Parameter</a> for details.)</p>

<p>Note that the fully qualified host name was provided.  Note also the use of the ca+domain value for the tlsvalidate parameter.  With these parameters, in addition to validating that the server's certificate was signed by a trusted certificate authority, the domain name portion of the host name will also be validated.  If the certificate contains Subject Alternative Names, then the domain name portion of the host name will be compared to the domain name portion of each of them.  If no Subject Alternative Names are provided then the domain name portion of the host name will be compared to the domain name portion of the certificate's Common Name.  The session will only continue if the sever's certificate and domain identity are both valid.</p>

<br/><p>For an even more secure session, the server may also request a certificate from the client, validate the certificate, and optionally authorize the client based on the host name provided by the certificate.</p>

<p>The following configuration enables these checks for an instance of SQL relay:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font>
		<font color="#009900">tls</font><font color="#990000">=</font><font color="#FF0000">"yes"</font>
		<font color="#009900">tlscert</font><font color="#990000">=</font><font color="#FF0000">"/usr/local/firstworks/etc/sqlrserver.pem"</font>
		<font color="#009900">tlsvalidate</font><font color="#990000">=</font><font color="#FF0000">"yes"</font>
		<font color="#009900">tlsca</font><font color="#990000">=</font><font color="#FF0000">"/usr/local/firstworks/etc/myca.pem"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlrclient1.firstworks.com"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlrclient2.firstworks.com"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlrclient3.firstworks.com"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlrclient4.firstworks.com"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<ul>
  <li>The <b>tlsvalidate</b> parameter enables (or disables) validation that client's certificate was signed by a trusted certificate authority, known to the system, or as provided by the tlsca parameter.</li>
  <li>The <b>tlsca</b> parameter specifies a certificate authority to include when validating the client's certificate.  This is useful when validating self-signed certificates.  (See <a href="tlsca.html">The tlsca Parameter</a> for details)</li>
  <li>User list auth is also used.  Database and proxied auth are not currently supported with TLS/SSL.</li>
</ul>

<p>Note that no passwords are required in the user list.  In this configuration, the Subject Alternative Names in the client's certificate (or Common Name of no SAN's are present) are authorized against the list of valid names.</p>

<p>To access the instance, the client must provide, at minimum, a certificate chain file (containing the client's certificate, private key, and signing certificates, as appropriate), as follows:</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver -tls -tlsvalidate no -tlscert /usr/local/firstworks/etc/sqlrclient.pem
</pre>

</blockquote>
<p>(.pem files are specified in this example, but on Windows systems, .pfx file or Windows Certificate Store references must be used.  See <a href="tlscert.html">The tlscert Parameter</a> for details.)</p>

<p>Note the absence of user and password parameters.  Rather than passing a user and password, the client passes the specified certificate to the server.  The server trusts that the client is who they say they are by virtue of having a valid certificate and the name provided by the certificate is authorized against the list of valid names.</p>

<p>In a more likely use case though, mutual authentication occurs - the client validates the server's certificate and the server validates the client's certificate, as follows:</p>

<blockquote>
  <pre>sqlrsh -host sqlrserver.firstworks.com -tls -tlscert /usr/local/firstworks/etc/sqlrclient.pem -tlsvalidate ca+host -tlsca /usr/local/firstworks/etc/myca.pem
</pre>

</blockquote>
<p>(.pem files are specified in this example, but on Windows systems, .pfx file or Windows Certificate Store references must be used.  See <a href="tlscert.html">The tlscert Parameter</a> and <a href="tlsca.html">The tlsca Parameter</a> for details.)</p>

<p>In this example, the client provides a certificate for the server to validate, validates the host's certificate against the provided certificate authority, and validates the host's identity against the provided host name.</p>

<p>While TLS/SSL authenticated and encrypted sessions are substantially more secure than standard SQL Relay sessions, several factors contribute to a performance penalty:</p>

<ul>
  <li>When establishing the secure session, a significant amount of data must be sent back and forth between the client and server over multiple network round-trips.</li>
  <li>Some TLS/SSL implementations impose a limit on the amount of data that can be sent or received at once, so more round trips may be required when processing queries.</li>
  <li>Without dedicated encryption hardware and a TLS/SSL implementation that supports it, the computation involved in encrypting and decrypting data can also introduce delays.</li>
</ul>

<p>Any kind of full SQL Relay session encryption should be used with caution in performance-sensitive applications.</p>

<hr/>

<br/><a name="security"/><h2>Security Features</h2>

<p>SQL Relay offers several features to enhance security.</p>

<br/><a name="krbtls"/><h3>Kerberos/Active Directory and TLS/SSL Encryption and Authentication</h3>

<p>As mentioned in the <a href="#authoptions">Authentication/Authorization Options</a> section above, SQL Relay supports <a href="#krb">Kerberos and Active Directory Encryption and Authentication</a> and <a href="#tls">TLS/SSL Encryption and Authentication</a>.</p>

<br/><a name="runas"/><h3>Run-As User and Group</h3>

<p>When a non-root user runs sqlr-start, the SQL Relay server runs as that user and as the primary group of that user.</p>

<p>When root runs sqlr-start, the SQL Relay server runs as a more secure user and group, usually nobody/nobody when built from source, or sqlrelay/sqlrelay when installed from packages.</p>

<p>However, the runasuser and runasgroup attributes can be used to control what user and group the SQL Relay server runs as.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> ... <font color="#009900">runasuser</font><font color="#990000">=</font><font color="#FF0000">"exampleuser"</font> <font color="#009900">runasgroup</font><font color="#990000">=</font><font color="#FF0000">"examplegroup"</font> ...<b><font color="#0000FF">&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>There are several important considerations when setting runasuser/runasgroup:</p>

<ul>
  <li>runasuser is only effective if sqlr-start is run as root.</li>
  <li>runasgroup only effective if sqlr-start is run by a member of the group, or by root.</li>
  <li>All SQL Relay configuration files, and any appropriate database configuration files (such as Oracle's tnsnames.ora and SAP/Sybase's interfaces file) must be readable by the runasuser/runasgroup.  Otherwise various things will fail, most notably, dynamic scaling.</li>
  <li>SQL Relay must be able to write to "run" and "log" directories.  However, when installed from RPM packages, the /var/run/sqlrelay and /var/log/sqlrelay directories are owned by sqlrelay/sqlrelay and have fairly restrictive 755 permissions.  Thus, the permissions on these directories must be manually changed if runasuser or runasgroup are set to any value other than "sqlrelay".  This is not an issue if SQL Relay is built from source, and is not an issue on Windows.</li>
</ul>

<br/><br/><a name="deniedallowedips"/><h3>Allowed/Denied IP Addresses</h3>

<p>By default, clients from any IP address are allowed to connect to the SQL Relay srever.  However, the deinedips and allowedips attributes can be used to restrict the set of IP addresses that clients can connect from.</p>

<p>The deniedips attribute can be configured with a <a target="_blank" href="http://www.regular-expressions.info">regular expression</a> indicating which IP address will be denied access.  The allowedips attribute can also be configured with a <a target="_blank" href="http://www.regular-expressions.info">regular expression</a> to override the deniedips attribute.</p>

<p>For example, to deny all clients except clients connecting from the 192.168.2.0 and 64.45.22.0 networks:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> ... <font color="#009900">deniedips</font><font color="#990000">=</font><font color="#FF0000">".*"</font> <font color="#009900">allowedips</font><font color="#990000">=</font><font color="#FF0000">"(192\.168\.2\..*|64\.45\.22\..*)"</font> ...<b><font color="#0000FF">/&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<br/><br/><a name="pwdenc"/><h3>Password Encryption</h3>

<p>Password encryption allows you to store passwords in the configuration file in a manner that makes them not directly readable.  Passwords for SQL Relay users and database passwords may both be encrypted.</p>

<p>Encryption and decryption are achieved via loadable modules.  The <i>passwordencryptions</i> section of the configuration file indicates which modules to load, and parameters in the user and connection tags indicate which module to use with the password defined in that same tag.</p>

<p>For example, to use the <i>rot</i> module, which encrypts by performing a simple character rotation:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;passwordencryptions&gt;</font></b>
			<b><font color="#0000FF">&lt;passwordencryption</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"rot"</font> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"rot13"</font> <font color="#009900">count</font><font color="#990000">=</font><font color="#FF0000">"13"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/passwordencryptions&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"test"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"grfg"</font> <font color="#009900">passwordencryptionid</font><font color="#990000">=</font><font color="#FF0000">"rot13"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"db"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=testuser;password=grfgcnffjbeq;..."</font> <font color="#009900">passwordencryptionid</font><font color="#990000">=</font><font color="#FF0000">"rot13"</font> <font color="#009900">metric</font><font color="#990000">=</font><font color="#FF0000">"6"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The <i>module</i> attribute specifies which module to load.</p>

<p>Module configurations may have attributes and/or nested tags.  How these are interpreted is module-specific.</p>

<p>In this example, the <i>id</i> and <i>count</i> attributes are parameters for the <i>rot</i> module.  "13" tells the module to rotate by 13 characters.  The <i>id</i> attribute assigns this particular module configuration an id that will be referenced by user and connection tags.  The <i>id</i> attribute is mandatory.</p>

<p>Note that the password in the user tag is encrypted (unencrypted, it would just be "test") and that the password in the string attribute of the connection tag is also encrypted (unencrypted, it would just be "testpassword").  A command line program (described later) is provided to encrypt passwords.</p>

<p>Note also that the passwordencryptionid attribute in both tags refers to the id of the module as set using the <i>id</i> parameter in the passwordencryption tag ( <i>rot13</i> ), not the module name ( <i>rot</i> ).</p>

<p>Password encryption modules may be "stacked".  It is possible to load multiple modules and use each one with a different password.  For example, you might want to use the <i>rot</i> module with a count of 13 for the SQL Relay password and a count of 10 for the database password.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;passwordencryptions&gt;</font></b>
			<b><font color="#0000FF">&lt;passwordencryption</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"rot"</font> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"rot13"</font> <font color="#009900">count</font><font color="#990000">=</font><font color="#FF0000">"13"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;passwordencryption</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"rot"</font> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"rot10"</font> <font color="#009900">count</font><font color="#990000">=</font><font color="#FF0000">"10"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/passwordencryptions&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"test"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"grfg"</font> <font color="#009900">passwordencryptionid</font><font color="#990000">=</font><font color="#FF0000">"rot13"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"db"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=testuser;password=docdzkccgybn;..."</font> <font color="#009900">passwordencryptionid</font><font color="#990000">=</font><font color="#FF0000">"rot10"</font> <font color="#009900">metric</font><font color="#990000">=</font><font color="#FF0000">"6"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>Encryption modules may be either two-way or one-way.  Two-way encryption modules can both encrypt and decrypt a password.  One-way encryption modules can only encrypt a password.</p>

<p>Symmetric and asymmetric key encryption techniques are two-way.  The rot encryption is an example of symmetric key encryption.  Asymmetric key encryptions generally use a public/private key pair, where the publicly available key is be used to encrypt the data but a privately held key is required to decrypt it.  SQL Relay can use two-way encryption modules with passwords for SQL Relay users and database passwords.</p>

<p>One-way encryption techniques include DES, MD5 and SHA1 hashes.  When using those techniques, the password can be encrypted but cannot effectively be decrypted.  SQL Relay can use one-way encryption moudles with passwords for SQL Relay users but can not use one-way encryption modules to encrypt database passwords.</p>

<p>The command line tool <b>sqlr-pwdenc</b> is provided to help encrypt passwords for inclusion in the configuration file.  Given an encryption module and password, it will print out the encrypted password.</p>

<blockquote>
  <pre>sqlr-pwdenc [-config configfile] -id id -pwdencid passwordencryptionid -password password
</pre>

</blockquote>
<ul>
  <li><b>configfile</b> - optional and refers to the configuration file</li>
  <li><b>id</b> - the instance within the configuration file to look for the specified password encryption module definition</li>
  <li><b>passwordencryptionid</b> - the id of the password encryption module to use</li>
  <li><b>password</b> - the password to encrypt</li>
</ul>

<p>For example:</p>

<blockquote>
  <pre>$ sqlr-pwdenc -id example -pwdencid rot13 -password testpassword
grfgcnffjbeq
</pre>

</blockquote>
<p>The resulting string "grfgcnffjbeq" can now be put in the configuration file as the password.</p>

<p>There is one final thing to note.  Command line client programs like sqlrsh and sqlr-import take a -id option.  The -id option causes the program to open the configuration file and extract the host, port, socket, user and password from the specified instance.  If the password is encrypted, then the encrypted password will be extracted and passed to the server.  This will fail.  So, when using the -id option with an encrypted password, you must also use the -user and -password option, to override the user/password that are extracted from the configuration file.</p>

<p>For example, rather than just using:</p>

<blockquote>
  <pre>sqlrsh -id example
</pre>

</blockquote>
<p>You should use:</p>

<blockquote>
  <pre>sqlrsh -id example -user test -password test
</pre>

</blockquote>
<p>Currently, the following password encryption modules are available in the standard SQL Relay distribution:</p>

<ul>
  <li>rot</li>
  <li>md5</li>
  <li>crypt</li>
</ul>

<p>The <b>rot</b> module is a two-way encryption module that performs a character rotation, similar to the popular <a target="_blank" href="http://en.wikipedia.org/wiki/ROT13">ROT13</a> algorithm, though it can rotate by any amount specified in the <i>count</i> attribute, not just 13 and rotates digits as well as upper and lower-case characters.</p>

<p>The <b>md5</b> module is a one-way encryption module that encrypts the password using the <a target="_blank" href="http://en.wikipedia.org/wiki/MD5">MD5</a> algorithm.</p>

<p>The <b>crypt</b> module is a one-way encryption module that encrypts the password using the <a target="_blank" href="http://en.wikipedia.org/wiki/Data_Encryption_Standard">DES</a> algorithm using a salt specified in the <i>salt</i> attribute.  The salt is required and must be a 2 digit alphanumeric code.</p>

<p>Custom modules may also be developed.  For more information, please contact <a href="mailto:dev@firstworks.com">dev@firstworks.com</a>. <a target="_blank" href="http://sqlrelay.sourceforge.net/images/us.png"><img src="http://sqlrelay.sourceforge.net/images/us.png"/></a> <a target="_blank" href="http://sqlrelay.sourceforge.net/images/br.png"><img src="http://sqlrelay.sourceforge.net/images/br.png"/></a></p>

<br/><a name="schedules"/><h3>Connection Schedules</h3>

<p>Connection schedules allow the SQL Relay server to control when users are allowed to access the database.</p>

<p>Connection schedules are implemented by loadable modules.  The <i>schedules</i> section of the configuration file indicates which modules to load and what parameters to use when executing them.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;schedules&gt;</font></b>
			<i><font color="#9A1900">&lt;!-- allow these users during business hours --&gt;</font></i>
			<b><font color="#0000FF">&lt;schedule</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"cron_userlist"</font> <font color="#009900">default</font><font color="#990000">=</font><font color="#FF0000">"deny"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;users&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"dmuse"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"kmuse"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"imuse"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"smuse"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/users&gt;</font></b>
				<b><font color="#0000FF">&lt;rules&gt;</font></b>
					<b><font color="#0000FF">&lt;allow</font></b> <font color="#009900">when</font><font color="#990000">=</font><font color="#FF0000">"* * * 2-5 8:00-11:59,13:00-16:59"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/rule&gt;</font></b>
			<b><font color="#0000FF">&lt;/schedule&gt;</font></b>
		<b><font color="#0000FF">&lt;/schedules&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The <i>module</i> attribute specifies which module to load.</p>

<p>Module configurations may have attributes and/or nested tags.  How these are interpreted is module-specific.</p>

<p>All schedule modules have an <i>enabled</i> parameter, allowing the module to be temporarily disabled.  If enabled="no" is configured, then the module is disabled.  If set to any other value, or omitted, then the module is enabled.</p>

<p>Connection schedule modules can be "stacked".  Multiple different modules may be loaded, and multiple instances of the same type of module, with different configurations, may also be loaded.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;schedules&gt;</font></b>
			<i><font color="#9A1900">&lt;!-- allow these users during business hours --&gt;</font></i>
			<b><font color="#0000FF">&lt;schedule</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"cron_userlist"</font> <font color="#009900">default</font><font color="#990000">=</font><font color="#FF0000">"deny"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;users&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"imuse"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"smuse"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/users&gt;</font></b>
				<b><font color="#0000FF">&lt;rules&gt;</font></b>
					<b><font color="#0000FF">&lt;allow</font></b> <font color="#009900">when</font><font color="#990000">=</font><font color="#FF0000">"* * * 2-5 8:00-11:59,13:00-16:59"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/rule&gt;</font></b>
			<b><font color="#0000FF">&lt;/schedule&gt;</font></b>

			<i><font color="#9A1900">&lt;!-- allow these users at any time --&gt;</font></i>
			<b><font color="#0000FF">&lt;schedule</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"cron_userlist"</font> <font color="#009900">default</font><font color="#990000">=</font><font color="#FF0000">"deny"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;users&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"dmuse"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"kmuse"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/users&gt;</font></b>
				<b><font color="#0000FF">&lt;rules&gt;</font></b>
					<b><font color="#0000FF">&lt;allow</font></b> <font color="#009900">when</font><font color="#990000">=</font><font color="#FF0000">"* * * * *"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/rule&gt;</font></b>
			<b><font color="#0000FF">&lt;/schedule&gt;</font></b>
		<b><font color="#0000FF">&lt;/schedules&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>At startup, the SQL Relay server creates instances of the specified schedule modules and initializes them.  When a client connects, the server passes the supplied credentials to each module, in the order that they were specified in the config file.  Each module applies its rules to the specified user.  If a module denies access to a user then the remaining modules are ignored.  If the user makes it through all modules without being denies access, then the user is allowed access.</p>

<p>Currently, only the ''cron_userlist'' connection schedule module is available in the standard SQL Relay distribution.  Custom modules may be developed though.  For more information, please contact <a href="mailto:dev@firstworks.com">dev@firstworks.com</a>. <a target="_blank" href="http://sqlrelay.sourceforge.net/images/us.png"><img src="http://sqlrelay.sourceforge.net/images/us.png"/></a> <a target="_blank" href="http://sqlrelay.sourceforge.net/images/br.png"><img src="http://sqlrelay.sourceforge.net/images/br.png"/></a></p>

<p>The <b>cron_userlist</b> module allows you to define a connection schedule for a list of users, using a cron-like syntax.</p>

<p><b>Note though, that the time-and-date fields have different meanings from traditional cron.</b></p>

<p>An example configuration follows.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;schedules&gt;</font></b>
			<i><font color="#9A1900">&lt;!-- allow these users during business hours --&gt;</font></i>
			<b><font color="#0000FF">&lt;schedule</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"cron_userlist"</font> <font color="#009900">default</font><font color="#990000">=</font><font color="#FF0000">"deny"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;users&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"dmuse"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"kmuse"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"imuse"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"smuse"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/users&gt;</font></b>
				<b><font color="#0000FF">&lt;rules&gt;</font></b>
					<b><font color="#0000FF">&lt;allow</font></b> <font color="#009900">when</font><font color="#990000">=</font><font color="#FF0000">"* * * 2-5 8:00-11:59,13:00-16:59"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/rule&gt;</font></b>
			<b><font color="#0000FF">&lt;/schedule&gt;</font></b>
		<b><font color="#0000FF">&lt;/schedules&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>In this example, the module denies access to all users by default, but then allows access to the dmuse, kmuse, imuse, and smuse users during business hours.  In this case, business hours are defined as:</p>

<ul>
  <li>every year</li>
  <li>every month</li>
  <li>every day of the month</li>
  <li>between days 2-5 (Monday-Friday) of the week</li>
  <li>between 8:00AM and 11:59AM and 1:00PM and 4:59PM</li>
</ul>

<p>Another example configuration follows.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;schedules&gt;</font></b>
			<i><font color="#9A1900">&lt;!-- deny these users during non-business hours --&gt;</font></i>
			<b><font color="#0000FF">&lt;schedule</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"cron_userlist"</font> <font color="#009900">default</font><font color="#990000">=</font><font color="#FF0000">"allow"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;users&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"dmuse"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"kmuse"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"imuse"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"smuse"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/users&gt;</font></b>
				<b><font color="#0000FF">&lt;rules&gt;</font></b>
					<b><font color="#0000FF">&lt;deny</font></b> <font color="#009900">when</font><font color="#990000">=</font><font color="#FF0000">"* * * 2-5 00:00-7:59,12:00-12:59,17:00-23:59"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;deny</font></b> <font color="#009900">when</font><font color="#990000">=</font><font color="#FF0000">"* * * 1,7 *"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/rules&gt;</font></b>
			<b><font color="#0000FF">&lt;/schedule&gt;</font></b>
		<b><font color="#0000FF">&lt;/schedules&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>In this example, the module allows access to all users by default, but then denies access to the dmuse, kmuse, imuse, and smuse users during non-business hours.  In this case, non-business hours are defined as:</p>

<ul>
  <li>every year</li>
  <li>every month</li>
  <li>every day of the month</li>
  <li>between days 2-5 (Monday-Friday) of the week</li>
  <ul>
    <li>between 12:00AM and 7:59AM</li>
    <li>between 12:00PM and 12:59PM</li>
    <li>between 5:00PM and 11:59PM</li>
  </ul>

  <li>on days 1 and 7 (Saturday and Sunday) of the week, at all hours</li>
</ul>

<p>The <b>users</b> tag defines a list of users to apply the schedule to.  It may contain any number of <b>user</b> tags.</p>

<p>The <b>user</b> tags support the following attributes:</p>

<ul>
  <li><b>user</b> - the name of a user or * meaning "all users"</li>
</ul>

<p>If a user does not appear in this list then it is granted access at any time.  If a user appears in the list then the schedule will be applied to that user.</p>

<p>The <b>default</b> attribute of the <b>schedule</b> tag defines the default rule.</p>

<ul>
  <li><b>allow</b> - allow access to the list of users unless they are denied access by the set of rules</li>
  <li><b>deny</b> - deny access to the list of users unless they are allowed access by the set of rules</li>
</ul>

<p>The <b>rules</b> tag defines the list of rules that modify the default behavior.  It may contain <b>allow</b> or <b>deny</b> tags.</p>

<p>The <b>allow</b> and <b>deny</b> tags support the following attributes:</p>

<ul>
  <li><b>when</b> - the years, months, days of month, days of week, and times of day that the rule applies to</li>
</ul>

<p>The format of the <b>when</b> attribute is cron-like.  There are 5 fields, separated by spaces.</p>

<p><b>Note again though, that the time-and-date fields have different meanings from traditional cron.</b></p>

<p>The fields represent, in order:</p>

<ul>
  <li>years</li>
  <li>months (where 1=January)</li>
  <li>days of the month</li>
  <li>days of the week (where 1=Sunday)</li>
  <li>times of day, in 24-hour format</li>
</ul>

<p>In each field, ranges may be specified with a dash, and sets may be separated by commas.  A * means "all possible values".</p>

<p>For example:</p>

<p>All day, every day, at any time of day:</p>

<blockquote>
  <pre>* * * * *
</pre>

</blockquote>
<p>All day, every month, on the 1st, 3rd through 5th, 8th, and 10th through 12th of the month:</p>

<blockquote>
  <pre>* * 1,3-5,8,10-12 * *
</pre>

</blockquote>
<p>Every day from 8:00AM through 11:59AM and 1:00PM through 4:59PM:</p>

<blockquote>
  <pre>* * * * 8:00-11:59,13:00-16:59
</pre>

</blockquote>
<p>Every day from 1:00PM to 4:00PM:</p>

<blockquote>
  <pre>* * * * 13:00-16:00
</pre>

</blockquote>
<p>All day, every Saturday:</p>

<blockquote>
  <pre>* * * 6 *
</pre>

</blockquote>
<p>All day, every day, in February and March:</p>

<blockquote>
  <pre>* 2,3 * * *
</pre>

</blockquote>
<p>Every day in February and March, from noon to 3PM:</p>

<blockquote>
  <pre>* 2,3 * * 12:00-15:00
</pre>

</blockquote>
<p>...and so on.</p>

<p>In general, the module works as follows:</p>

<ul>
  <li>When a user connects, the module looks for the user in the list of users.</li>
  <ul>
    <li>If the user is not found then access is granted.</li>
    <li>If the user is found, then the default rule is applied.</li>
    <ul>
      <li>Each rule in the rules list is evaluated.</li>
      <ul>
        <li>If the rule doesn't apply to the current time, then it is ignored.</li>
        <li>If the rule does apply to the current time, then it is applied.</li>
        <ul>
          <li>Each rule may reverse the outcome the previous rules.</li>
        </ul>

      </ul>

      <li>When all rules have been applied, the user will have been allowed or denied access.</li>
    </ul>

  </ul>

</ul>

<br/><br/><a name="filtering"/><h3>Query Filtering</h3>

<p>Query Filter modules allow the SQL Relay server programs to filter out queries, and not pass them along to the database.</p>

<p>Query filters are implemented by loadable modules.  The <i>filters</i> section of the configuration file indicates which filter modules to load and what parameters to use when executing them.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>
	...
	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;filters&gt;</font></b>
			<b><font color="#0000FF">&lt;filter</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">" [0-9]*=[0-9]*"</font> <font color="#009900">errornumbrer</font><font color="#990000">=</font><font color="#FF0000">"100"</font> <font color="#009900">error</font><font color="#990000">=</font><font color="#FF0000">"regex filter violation"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/filters&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>
	...
<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The <i>module</i> attribute specifies which module to load.</p>

<p>Module configurations may have attributes and/or nested tags.  How these are interpreted is module-specific.</p>

<p>All filter modules have an <i>enabled</i> parameter, allowing the module to be temporarily disabled.  If enabled="no" is configured, then the module is disabled.  If set to any other value, or omitted, then the module is enabled.</p>

<p>All filter modules have an <i>when</i> parameter as well, which determines when the filter is applied.  If set to "before" then the module is executed before any query translations are executed.  If set to "after", or omitted, then the module is executed  after all query translations have been executed.  See <a href="#querytranslations">Query Translations</a> below for more information.</p>

<p>Filter modules can be "stacked".  Multiple different modules may be loaded and multiple instances of the same type of module, with different configurations, may also be loaded.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>
	...
	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;filters&gt;</font></b>
			<b><font color="#0000FF">&lt;filter</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">" [0-9]*=[0-9]*"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;filter</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^(create)"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;filter</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^(drop)"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;filter</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"string"</font> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"hugetable"</font> <font color="#009900">ignorecase</font><font color="#990000">=</font><font color="#FF0000">"yes"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;filter</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"string"</font> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"badschema"</font> <font color="#009900">ignorecase</font><font color="#990000">=</font><font color="#FF0000">"yes"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/filters&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>
	...
<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>At startup, the SQL Relay server creates instances of the specified filter modules and initializes them.  When a query is run, the server passes the query to each module, in the order that they were specified in the config file.  If a module filters out the query, then it isn't passed along to the next module, nor is it sent to the database, and the client program is told that the query failed.</p>

<p>When using query filters, it is helpful to use the <i>normalize</i> query translation too:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>
	...
	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;translations&gt;</font></b>
			<b><font color="#0000FF">&lt;translation</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"normalize"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/translations&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;filters&gt;</font></b>
			<b><font color="#0000FF">&lt;filter</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">" [0-9]*=[0-9]*"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/filters&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>
	...
<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>See <a href="#querytranslations">Query Translations</a> below for more information.</p>

<p>Currently, the following filter modules are available:</p>

<ul>
  <li><b>patterns</b></li>
  <li><b>regex</b></li>
  <li><b>string</b></li>
</ul>

<p>Custom modules may also be developed.  For more information, please contact <a href="mailto:dev@firstworks.com">dev@firstworks.com</a>. <a target="_blank" href="http://sqlrelay.sourceforge.net/images/us.png"><img src="http://sqlrelay.sourceforge.net/images/us.png"/></a> <a target="_blank" href="http://sqlrelay.sourceforge.net/images/br.png"><img src="http://sqlrelay.sourceforge.net/images/br.png"/></a></p>

<h4>patterns</h4>

<p>The <b>patterns</b> module matches the query against a specified set of patterns.  Each pattern may be a string, case-insensitive string, or regular expression.  Each pattern may also be matched against the entire query, only the parts of the query that are outside of quotes, or only the parts of the query that are contained within quotes.  If the query matches, then it is filtered out.</p>

<p>The list of patterns is given by a set of <b>pattern</b> child tags.  Each pattern tag may contain the following attributes.</p>

<ul>
  <li><b>pattern</b> - Required.  The pattern to match.</li>
  <li><b>type</b> - Optional.  Defaults to "string".  Valid values are "string", "cistring" (case insensitive string), and "regex" (regular expression).</li>
  <li><b>scope</b> - Optional.  Defaults to "query".  Valid values are "query" (attempt to match against the entire query), "outsidequotes" (only match parts of the query not surrounded by single-quotes), and "insidequotes" (only match parts of the query surrounded by single-quotes).</li>
  <li><b>errornumber</b> - Optional.  Defaults to 0.  The error number to return to the client if the query matches this filter.</li>
  <li><b>error</b> - Optional.  Defaults to an empty string.  The error string to return to the client if the query matches this filter.</li>
</ul>

<p>For example, with the following configuration...</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>
	...
	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;filters&gt;</font></b>
			<b><font color="#0000FF">&lt;filter</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"patterns"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^(drop|create)"</font> <font color="#009900">type</font><font color="#990000">=</font><font color="#FF0000">"regex"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"hugetable"</font> <font color="#009900">type</font><font color="#990000">=</font><font color="#FF0000">"cistring"</font> <font color="#009900">scope</font><font color="#990000">=</font><font color="#FF0000">"outsidequotes"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"badstring"</font> <font color="#009900">scope</font><font color="#990000">=</font><font color="#FF0000">"insidequotes"</font> <font color="#009900">errornumbrer</font><font color="#990000">=</font><font color="#FF0000">"100"</font> <font color="#009900">error</font><font color="#990000">=</font><font color="#FF0000">"pattern filter violation"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/filter&gt;</font></b>
		<b><font color="#0000FF">&lt;/filters&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>
	...
<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>These queries would be filtered out:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>drop table mytable
create <font color="#008080">table</font> <b><font color="#000000">mytable</font></b> <font color="#990000">(</font><font color="#008080">col1</font> <font color="#009900">int</font><font color="#990000">)</font>
select <font color="#990000">*</font> from HugeTable
select <font color="#990000">*</font> from badstringtable <font color="#008080">where</font> col1<font color="#990000">=</font><font color="#FF0000">'badstring'</font>
</tt></pre>

</blockquote>
<p>But these queries would not be:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>insert into <font color="#008080">mytable</font> <b><font color="#000000">values</font></b> <font color="#990000">(</font><font color="#993399">1</font><font color="#990000">)</font>
select <font color="#990000">*</font> from goodtable
select <font color="#990000">*</font> from badstringtable <font color="#008080">where</font> col1<font color="#990000">=</font><font color="#FF0000">'goodstring'</font>
</tt></pre>

</blockquote>
<h4>regex</h4>

<p>The <b>regex</b> module matches the query against a specified regular expression pattern.  If the query matches, then it is filtered out.  This module is useful if you need to do a quick match, without the complexity of the patterns module.</p>

<p>In addition to the module attribute, each filter tag may contain the following attributes.</p>

<ul>
  <li><b>pattern</b> - Required.  The pattern to match.</li>
  <li><b>errornumber</b> - Optional.  Defaults to 0.  The error number to return to the client if the query matches this filter.</li>
  <li><b>error</b> - Optional.  Defaults to an empty string.  The error string to return to the client if the query matches this filter.</li>
</ul>

<p>For example, with the following configuration:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>
	...
	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;filters&gt;</font></b>
			<b><font color="#0000FF">&lt;filter</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">" [0-9]*=[0-9]*"</font> <font color="#009900">errornumbrer</font><font color="#990000">=</font><font color="#FF0000">"100"</font> <font color="#009900">error</font><font color="#990000">=</font><font color="#FF0000">"regex filter violation"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/filters&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>
	...
<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>This query would be filtered out:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>select <font color="#990000">*</font> from mytable <font color="#008080">where</font> column1<font color="#990000">=</font><font color="#993399">1</font> and <font color="#993399">1</font><font color="#990000">=</font><font color="#993399">1</font>
</tt></pre>

</blockquote>
<p>But this query would not be:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>select <font color="#990000">*</font> from mytable <font color="#008080">where</font> column1<font color="#990000">=</font><font color="#993399">1</font>
</tt></pre>

</blockquote>
<h4>string</h4>

<p>The <b>string</b> module matches the query against a specified string pattern.  If the query matches, then it is filtered out.  This module is useful if you need to do a quick match without the complexity of regular expressions or of the patterns module.</p>

<p>In addition to the module attribute, each filter tag may contain the following attributes.</p>

<ul>
  <li><b>pattern</b> - Required.  The pattern to match.</li>
  <li><b>ignorecase</b> - Optional.  Defaults to "no".  If set to "yes" then the comparison is case insensitive.</li>
  <li><b>errornumber</b> - Optional.  Defaults to 0.  The error number to return to the client if the query matches this filter.</li>
  <li><b>error</b> - Optional.  Defaults to an empty string.  The error string to return to the client if the query matches this filter.</li>
</ul>

<p>For example, with the following configuration:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>
	...
	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;filters&gt;</font></b>
			<b><font color="#0000FF">&lt;filter</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"string"</font> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"hugetable"</font> <font color="#009900">ignorecase</font><font color="#990000">=</font><font color="#FF0000">"yes"</font> <font color="#009900">errornumbrer</font><font color="#990000">=</font><font color="#FF0000">"100"</font> <font color="#009900">error</font><font color="#990000">=</font><font color="#FF0000">"string filter violation"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/filters&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>
	...
<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>This query would be filtered out:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>select <font color="#990000">*</font> from hugetable
</tt></pre>

</blockquote>
<p>But this query would not be:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>select <font color="#990000">*</font> from goodtable <font color="#008080">where</font> column1<font color="#990000">=</font><font color="#993399">1</font>
</tt></pre>

</blockquote>
<hr/>

<br/><a name="translation"/><h2>Translation</h2>

<p>SQL Relay offers features for translating queries and result sets.</p>

<br/><a name="querytranslation"/><h3>Query Translation</h3>

<p>Query translation allows the SQL Relay server to alter queries before passing them to the database.</p>

<p>Query translation is implemented by loadable modules.  The <i>translations</i> section of the configuration file indicates which translation modules to load and what parameters to use when executing them.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>
	...
	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font> ... <b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;translations&gt;</font></b>
			<b><font color="#0000FF">&lt;translation</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"normalize"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/translations&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>
	...
<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The <i>module</i> attribute specifies which module to load.</p>

<p>Module configurations may have attributes and/or nested tags.  How these are interpreted is module-specific.</p>

<p>All translation modules have an <i>enabled</i> parameter, allowing the module to be temporarily disabled.  If enabled="no" is configured, then the module is disabled.  If set to any other value, or omitted, then the module is enabled.</p>

<p>At startup, the SQL Relay server creates instances of the specified translations modules and initializes them.  When a query is run, the server passes the query to each module, in the order that they were specified in the config file.  If a module modifies the query, then that modified query is passed on to the next module.</p>

<p>Currently, the following translation module is available:</p>

<ul>
  <li><b>normalize</b></li>
</ul>

<p>Custom modules may also be developed.  For more information, please contact <a href="mailto:dev@firstworks.com">dev@firstworks.com</a>. <a target="_blank" href="http://sqlrelay.sourceforge.net/images/us.png"><img src="http://sqlrelay.sourceforge.net/images/us.png"/></a> <a target="_blank" href="http://sqlrelay.sourceforge.net/images/br.png"><img src="http://sqlrelay.sourceforge.net/images/br.png"/></a></p>

<p>The <b>normalize</b> module performs the following operations on a query:</p>

<ul>
  <li>Removes comments.</li>
  <li>Converts all white-space characters to spaces, outside of quoted strings.</li>
  <li>Converts multiple spaces into a single space, outside of quoted strings.</li>
  <li>Removes whitespace from around operators.</li>
  <li>Converts static concatenations to equivalent strings.  Eg. converts 'he' || 'll' || 'o' to 'hello'.</li>
  <li>Optionally converts the query to lower or upper case as specified by parameters described below.</li>
  <li>Optionally converts comma-separated decimals to dot-separated decimals.</li>
  <li>Optionally removes double-quotes around database object names.</li>
</ul>

<p>For example, the following query:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>sElEcT
	<font color="#990000">*,</font>
	<font color="#FF0000">'He'</font> <font color="#990000">||</font> <font color="#FF0000">'Ll'</font> <font color="#990000">||</font> <font color="#FF0000">'o'</font>
from
	myTABLE
where
	myTaBLe<font color="#990000">.</font>CoLuMn1    <font color="#990000">=</font>     myTablE<font color="#990000">.</font>ColuMN2  <font color="#990000">/</font>    <font color="#993399">2</font>
</tt></pre>

</blockquote>
<p>Would be translated to:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>select <font color="#990000">*,</font> <font color="#FF0000">'HeLlo'</font> from mytable <font color="#008080">where</font> mytable<font color="#990000">.</font>column1 <font color="#990000">=</font> mytable<font color="#990000">.</font>column2<font color="#990000">/</font><font color="#993399">2</font>
</tt></pre>

</blockquote>
<p>Normalizing a query is useful when also using <a href="#filtering">query filtering</a> as it simplifies the patterns that have to be searched for.</p>

<p>The following parameters are currently supported:</p>

<ul>
  <li><b>foreigndecimals</b> - "yes" or "no".  Defaults to "no".</li>
  <ul>
    <li>SQL requires dots for decimal separators.  However, some internationalized apps are not well behaved and build queries with decimals that use commas for decimal separators.  This parameter instructs the module to try to identify comma-separated decimals and replace the commas with dots.</li>
    <li>This can be tricky, especially with decimals in parentheses, which can be misinterpreted as parameters.  To help manage this, a space before a set of comma-separated numbers is interpreted as a delimiter, and no number may have more than 1 decimal separator.</li>
    <li>For example:</li>
    <ul>
      <li>(111,222, 333,444) is interpreted as having 2 decimals: 111.222 and 333.444</li>
      <li>(111, 222, 333,444) is interpreted as having 2 integers and 1 decimal: 111 and 222 and 333.444</li>
      <li>(111,222, 333,444,555) is interpreted as having 2 decimals and 1 integer: 111.222 and 333.444 and 555</li>
      <li>(111,222) is interpreted as 2 integers: 111 and 222</li>
      <li>( 111,222) is interpreted as 1 decimal: 111.222</li>
      <li>etc.</li>
    </ul>

  </ul>

  <li><b>convertcase</b> - "upper", "lower", or "no".  Defaults to "lower".</li>
  <ul>
    <li>If set to "upper" or "lower" then the entire query is converted to the specified case, except for strings surrounded by single or double quotes.</li>
    <li>If set to "no" then no case conversion is done.</li>
    <li>If omitted then the value defaults to "lower".</li>
  </ul>

  <li><b>convertcasedoublequoted</b> - "upper", "lower", "yes", or "no".  Defaults to "no".</li>
  <ul>
    <li>If set to "upper" or "lower" then values enclosed in double-quotes are converted to the specified case.  Double-quotes usually surround the names of database objects such as table, index, or column names to indicate that they should be interpreted in a case-sensitive manner.  So, effectively, setting this to "yes" forces the case of the quoted object names in the query.</li>
    <ul>
      <li>Some databases (eg. Oracle) default object names to upper case when creating the object, if the object names are unquoted in the create statement.</li>
      <ul>
        <li>Eg. 'create table test (col1 int)' creates a table named <i>TEST</i> with a column named <i>COL1</i>.</li>
      </ul>

      <li>Some databases (eg. PostgreSQL, MySQL, others) default object names to the specified case when creating the object, if the object names are unquoted in the create statement.</li>
      <ul>
        <li>Eg. 'create table test (col1 int)' creates a table named <i>test</i> with a column named <i>col1</i>.</li>
      </ul>

      <li>This can be useful when converting an app from one type of database to the other if the app's queries contain quoted object names.</li>
    </ul>

    <li>If set to "yes" then values enclosed in double-quotes are converted to the case specified by the convertcase parameter.</li>
    <li>If set to "no" then no case conversion is done.</li>
    <li>If omitted then the value defaults to "no".</li>
  </ul>

  <li><b>removedoublequotes</b> - "yes" or "no".  Defaults to "no".</li>
  <ul>
    <li>If set to "yes" then double-quotes are removed, except for escaped double quotes.  Double-quotes usually surround the names of database objects such as table, index, or column names to indicate that they should be interpreted in a case-sensitive manner.  So, effectively, setting this to "yes" causes the database to interpret the object names case-insensitively.</li>
    <ul>
      <li>Some databases (eg. Oracle) default object names to upper case when creating the object, if the object names are unquoted in the create statement.</li>
      <ul>
        <li>Eg. 'create table test (col1 int)' creates a table named <i>TEST</i> with a column named <i>COL1</i>.</li>
      </ul>

      <li>Some databases (eg. PostgreSQL, MySQL, others) default object names to the specified case when creating the object, if the object names are unquoted in the create statement.</li>
      <ul>
        <li>Eg. 'create table test (col1 int)' creates a table named <i>test</i> with a column named <i>col1</i>.</li>
      </ul>

      <li>This can be useful when converting an app from one type of database to the other if the app's queries contain quoted object names.</li>
    </ul>

    <li>If set to "no" then double-quotes are not removed.</li>
    <li>If omitted then the value defaults to "no".</li>
  </ul>

</ul>

<br/><a name="resultsettranslation"/><h3>Result Set Translation</h3>

<p>Result set translation allows the SQL Relay server to alter fields in the result set before returning the field to the client.</p>

<p>Result set translation is implemented by loadable modules.  The <i>resultsettranslations</i> section of the configuration file indicates which result set translation modules to load and what parameters to use when executing them.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;resultsettranslations&gt;</font></b>
			<b><font color="#0000FF">&lt;resultsettranslation</font></b>
				<font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"reformatdatetime"</font>
				<font color="#009900">datetimeformat</font><font color="#990000">=</font><font color="#FF0000">"MM/DD/YYYY HH24:MI:SS"</font>
				<font color="#009900">dateformat</font><font color="#990000">=</font><font color="#FF0000">"MM/DD/YYYY"</font>
				<font color="#009900">timeformat</font><font color="#990000">=</font><font color="#FF0000">"HH24:MI:SS"</font>
				<font color="#009900">dateddmm</font><font color="#990000">=</font><font color="#FF0000">"yes"</font>
				<font color="#009900">ignorenondatetime</font><font color="#990000">=</font><font color="#FF0000">"yes"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/resultsettranslations&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The <i>module</i> attribute specifies which module to load.</p>

<p>Module configurations may have attributes and/or nested tags.  How these are interpreted is module-specific.</p>

<p>All result set translation modules have an <i>enabled</i> parameter, allowing the module to be temporarily disabled.  If enabled="no" is configured, then the module is disabled.  If set to any other value, or omitted, then the module is enabled.</p>

<p>At startup, the SQL Relay server creates instances of the specified result set translation modules and initializes them.  As each field of the result set is returned, the server passes the field to each module, in the order that they were specified in the config file.  If a module modifies a field, then that modified field is passed on to the next module.</p>

<p>Currently, the following result set translation module is available:</p>

<ul>
  <li><b>reformatdatetime</b></li>
</ul>

<p>Custom modules may also be developed.  For more information, please contact <a href="mailto:dev@firstworks.com">dev@firstworks.com</a>. <a target="_blank" href="http://sqlrelay.sourceforge.net/images/us.png"><img src="http://sqlrelay.sourceforge.net/images/us.png"/></a> <a target="_blank" href="http://sqlrelay.sourceforge.net/images/br.png"><img src="http://sqlrelay.sourceforge.net/images/br.png"/></a></p>

<p>The <b>reformatdatetime</b> module examines the field, decides if it's a date/time field, and if so, reformats it based on the given parameters.</p>

<p>The following parameters are currently supported:</p>

<ul>
  <li><b>datetimeformat</b> - Specifies the format to convert date/time fields to.  May be any combination of the following format characters.  Non-format characters will be inserted as-is.</li>
  <ul>
    <li><b>DD</b> - day of the month</li>
    <li><b>MM</b> - numeric month</li>
    <li><b>MON</b> - 3-character text abbreviation for the month</li>
    <li><b>Month</b> - full text month</li>
    <li><b>YYYY</b> - year including century</li>
    <li><b>YY</b> - year excluding century</li>
    <li><b>HH24</b> - hour (0-23)</li>
    <li><b>HH</b> - hour (1-12)</li>
    <li><b>MI</b> - minute</li>
    <li><b>SS</b> - second</li>
    <li><b>FFF</b> - fraction of a second</li>
    <li><b>AM</b> - AM or PM</li>
  </ul>

  <li><b>dateformat</b> - Similar to datetimeformat but if a date without the time component is detected, the supplied format will be used instead of the format supplied in the datetimeformat parameter.  Defaults to whatever value was supplied in the datetimeformat parameter.</li>
  <li><b>timeformat</b> - Similar to datetimeformat but if a time without the date component is detected, the supplied format will be used instead of the format supplied in the datetimeformat parameter.  Defaults to whatever value was supplied in the datetimeformat parameter.</li>
  <li><b>dateddmm</b> - If set to "yes" then dates are assumed to be in the DD-MM-YYYY format (with days leading), as opposed to MM-DD-YYYY format (with months leading).  This is important for interpreting dates like 03-04-2000.  If this parameter is set to "yes" then it would be interprted as March 4th rather than April 3rd.</li>
  <li><b>dateyyddmm</b> - If set to "yes" then dates are assumed to be in the YYYY-DD-MM format (with days leading), as opposed to YYYY-MM-DD-YYYY (with months leading).  This is important for interpreting dates like 2000-03-04.  If this parameter is set to "yes" then it would be interprted as March 4th rather than April 3rd.</li>
  <li><b>datedelimiters</b> - Determining whether the field is a date/time or not can be tricky.  Different cultures and systems delimit dates with different characteres, including slashes, dashes, colons and periods.  This parameter enables you to specify which of these to pay attention to.  For example, if your database contains both slash-delimited and dash-delimited dates, but also contains dot-delimited data that could be misinterpreted as a date, then you'd want to set this to "/-".  Defaults to "/-:."  Characters other than slash, dash, colon and dot are ignored.</li>
  <li><b>ignorenondatetime</b> - If this parameter is set to "yes" then only fields with date/time datatypes will be examined.  Char, and varchar fields, for example, will be ignored.  By default, all fields are examined and heuristics are used to determine whether the field contains a date/time.</li>
</ul>

<p>For example, the following configuration:</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;resultsettranslations&gt;</font></b>
			<b><font color="#0000FF">&lt;resultsettranslation</font></b>
				<font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"reformatdatetime"</font>
				<font color="#009900">datetimeformat</font><font color="#990000">=</font><font color="#FF0000">"MM/DD/YYYY HH24:MI:SS"</font>
				<font color="#009900">dateformat</font><font color="#990000">=</font><font color="#FF0000">"MM/DD/YYYY"</font>
				<font color="#009900">timeformat</font><font color="#990000">=</font><font color="#FF0000">"HH24:MI:SS"</font>
				<font color="#009900">dateddmm</font><font color="#990000">=</font><font color="#FF0000">"yes"</font>
				<font color="#009900">ignorenondatetime</font><font color="#990000">=</font><font color="#FF0000">"yes"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/resultsettranslations&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>Would translate the following date/time field:</p>

<blockquote>
Jul 10 2015 05:17:55:717PM
</blockquote>
<p>Into:</p>

<blockquote>
07/10/2015 17:18:55
</blockquote>
<p>Note that <b>dateddmm</b> and <b>dateyyddmm</b> should usually be set to the same thing.  There are very specific cases where these two parameters need to be set differently from one another.  You'll know if you need to.</p>

<p>Note also that date/time translation in general is especially problematic with MS SQL Server.  See <a href="../faq/#mssqldates">the FAQ</a> for more info.</p>

<hr/>

<br/><a name="queryrouting"/><h2>Query Routing</h2>

<p>Query routing allows the SQL Relay server to send one set of queries to one database, another set of queries to another, another set of queries to another, and so on.</p>

<p>To route queries, one instance of SQL Relay must be configured as a router to route queries to other instances of SQL Relay which are configured normally.</p>

<p>A typical use case is to configure one instance of SQL Relay to maintain connections to a master database and another instance of SQL Relay to maintain connections to a pool of slaves, then set up a third instance of SQL Relay to route queries to the other 2 instances.</p>

<blockquote>
<img src="../images/router.png"/>
</blockquote>
<p>This is such a common case, that it is also described above in it's own section: <a href="#masterslave">Master-Slave Query Routing</a>.</p>

<p>There are other possiblities as well though.</p>

<p>The actual query routing itself is implemented by loadable modules.  The <i>routers</i> section of the configuration file indicates which router modules to load and what parameters to use when executing them.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

        <b><font color="#0000FF">&lt;instance</font></b> ... <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"router"</font> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;routers&gt;</font></b>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"master"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^drop "</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^create "</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^insert "</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^update "</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^delete "</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"slave"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">".*"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
		<b><font color="#0000FF">&lt;/routers&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"master"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"..."</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"slave"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"..."</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
		...
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The <i>module</i> attribute specifies which module to load.</p>

<p>Module configurations may have attributes and/or nested tags.  How these elements are interpreted is module-specific.</p>

<p>All router modules have an <i>enabled</i> parameter, allowing the module to be temporarily disabled.  If enabled="no" is configured, then the module is disabled.  If set to any other value, or omitted, then the module is enabled.</p>

<p>Router modules can be "stacked".  Multiple modules may be loaded and multiple instances of the same type of module, with different configurations, may also be loaded.</p>

<p>In fact, the example above shows a stacked configuration.  The first instance of the router module sends DDL/DML queries to a "master" database and the second instance of the router module sends all other queries to a "slave" database.</p>

<p>At startup, the SQL Relay server creates instances of the specified router modules and initializes them.  When the client sends a query to the SQL Relay server, the server consults each router module, in the order that they were specified in the config file.  Each module applies its routing rules to determine which connection to run the query on.  If a module returns a connection then the remaining modules are ignored.  If the query makes it through all modules without being routed to a particular connection, then the query is ignored.</p>

<p>Currently, the following router modules are available:</p>

<ul>
  <li><a href="#regex">regex</a></li>
  <li><a href="#userlist">userlist</a></li>
  <li><a href="#clientiplist">clientiplist</a></li>
  <li><a href="#clientinfolist">lientinfolist</a></li>
  <li><a href="#usedatabase">usedatabase</a></li>
</ul>

<p>Custom modules may also be developed.  For more information, please contact <a href="mailto:dev@firstworks.com">dev@firstworks.com</a>. <a target="_blank" href="http://sqlrelay.sourceforge.net/images/us.png"><img src="http://sqlrelay.sourceforge.net/images/us.png"/></a> <a target="_blank" href="http://sqlrelay.sourceforge.net/images/br.png"><img src="http://sqlrelay.sourceforge.net/images/br.png"/></a></p>

<br/><a name="regex"/><h4>regex</h4>

<p>The <b>regex</b> module routes queries by matching them against regular expressions.</p>

<p>A classic <a href="#masterslave">Master-Slave Query Routing</a> configuration follows.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

        <i><font color="#9A1900">&lt;!-- This instance maintains connections to the "master" MySQL database</font></i>
<i><font color="#9A1900">                on the masterdb machine.  This instance only listens on the</font></i>
<i><font color="#9A1900">                unix socket /tmp/master.socket and thus cannot be connected to</font></i>
<i><font color="#9A1900">                by clients from another machine. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"master"</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/master.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"mysql"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"masteruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"masterpassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
                <b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=masteruser;password=masterpassword;host=masterdb;db=master;"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>


        <i><font color="#9A1900">&lt;!-- This instance maintains connections to 4 "slave" MySQL databases</font></i>
<i><font color="#9A1900">                on 4 slave machines.  This instance only listens on the unix</font></i>
<i><font color="#9A1900">                socket /tmp/slave.socket and thus cannot be connected to by</font></i>
<i><font color="#9A1900">                clients from another machine. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"slave"</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/slave.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"mysql"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"slaveuser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"slavepassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
                <b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=slaveuser;password=slavepassword;host=slavedb1;db=slave;"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=slaveuser;password=slavepassword;host=slavedb2;db=slave;"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=slaveuser;password=slavepassword;host=slavedb3;db=slave;"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=slaveuser;password=slavepassword;host=slavedb3;db=slave;"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>


        <i><font color="#9A1900">&lt;!-- This instance sends DML (insert,update,delete) and</font></i>
<i><font color="#9A1900">                DDL (create/delete) queries to the "master" SQL Relay instance</font></i>
<i><font color="#9A1900">                which, in turn, sends them to the "master" database.</font></i>
<i><font color="#9A1900">                This instance sends any other queries to the "slave" SQL Relay</font></i>
<i><font color="#9A1900">                instance which, in turn, distributes them over the "slave"</font></i>
<i><font color="#9A1900">                databases. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"router"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"router"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"routeruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"routerpassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;routers&gt;</font></b>
                        <i><font color="#9A1900">&lt;!-- send all DML/DDL queries to "master"  --&gt;</font></i>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"master"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^drop "</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^create "</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^insert "</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^update "</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"^delete "</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
                        <i><font color="#9A1900">&lt;!-- send all other queries to "slave" --&gt;</font></i>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"slave"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">".*"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
		<b><font color="#0000FF">&lt;/routers&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"master"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/master.socket;user=masteruser;password=masterpassword"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"slave"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/slave.socket;user=slaveuser;password=slavepassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>In this example, 3 SQL Relay instances are defined:</p>

<ul>
  <li>one to maintain connections to the master database</li>
  <li>one to maintain connections to a pool of slave databases</li>
  <li>one to route queries to the other two instances</li>
</ul>

<p>In this configuration, DDL/DML queries are routed to the connectionid "master", and all other queries are routed to the connectionid "slave".</p>

<p>The <b>string</b> parameter in each connection tag provides the parameters necessary to connect to the other instances.  Valid parameters include:</p>

<ul>
  <li><b>host</b> - the host name or IP address of the SQL Relay instance</li>
  <li><b>port</b> - the port of the SQL Relay instance</li>
  <li><b>socket</b> - the socket of the SQL Relay instance, if it is running locally</li>
  <li><b>user</b> - the user to use when connecting to the SQL Relay instance as</li>
  <li><b>password</b> - the password to use when connecting to the SQL Relay instance</li>
  <li><b>fetchatonce</b> - the number of rows to fetch at a time (defaults to 10, 0 means fetch the entire result set)</li>
</ul>

<p>Note the use of a notification module to notify <i>dba@firstworks.com</i> if an <i>integrity_violation</i> event occurs.  SQL Relay must maintain parallel transactions on all databases that a query may be routed to.  An integrity violation occurs when a transaction control query (begin, commit, rollback, autocommit on, or autocommit off) succeeds on some of the backends but fails on others.  See <a href="#notifications">Notifications</a> for information about notification modules.</p>

<br/><p>Master-slave routing isn't all that the <b>regex</b> module can do though.</p>

<p>In the example below, we provide a single point of access to MySQL and PostgreSQL databases.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<i><font color="#9A1900">&lt;!-- This instance maintains connections to a MySQL database --&gt;</font></i>
	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"mysqldb"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">""</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/mysqldb.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"mysql"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"mysqldbuser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"mysqldbpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=mysqldbuser;password=mysqldbpassword;host=mysqldb;db=mysqldb;"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>


	<i><font color="#9A1900">&lt;!-- This instance maintains connections to a PostgreSQL database --&gt;</font></i>
	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"postgresqldb"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">""</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/postgresqldb.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"postgresql"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"postgresqldbuser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"postgresqldbpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=postgresqldbuser;password=postgresqldbpassword;host=postgresqldb;db=postgresqldb;"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>


	<i><font color="#9A1900">&lt;!-- This instance sends queries containing "mysqldb." to the mysql</font></i>
<i><font color="#9A1900">		database and "postgresqldb." to the postgresql database --&gt;</font></i>
	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"router"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"router"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"routeruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"routerpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;routers&gt;</font></b>
			<i><font color="#9A1900">&lt;!-- send all mysqldb queries to "mysqldb" --&gt;</font></i>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"mysqldb"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"mysqldb\."</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
			<i><font color="#9A1900">&lt;!-- send all postgresqldb queries to "postgresqldb" --&gt;</font></i>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"regex"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"postgresqldb"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;pattern</font></b> <font color="#009900">pattern</font><font color="#990000">=</font><font color="#FF0000">"postgresqldb\."</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
		<b><font color="#0000FF">&lt;/routers&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"mysqldb"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/mysqldb.socket;user=mysqldbuser;password=mysqldbpassword"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"postgresqldb"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/postgresqldb.socket;user=postgresqldbuser;password=postgresqldbpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
		<b><font color="#0000FF">&lt;notifications&gt;</font></b>
			<b><font color="#0000FF">&lt;notification</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"events"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;events&gt;</font></b>
					<b><font color="#0000FF">&lt;event</font></b> <font color="#009900">event</font><font color="#990000">=</font><font color="#FF0000">"integrity_violation"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/events&gt;</font></b>
				<b><font color="#0000FF">&lt;recipients&gt;</font></b>
					<b><font color="#0000FF">&lt;recipient</font></b> <font color="#009900">address</font><font color="#990000">=</font><font color="#FF0000">"dba@firstworks.com"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/recipients&gt;</font></b>
			<b><font color="#0000FF">&lt;/notification&gt;</font></b>
		<b><font color="#0000FF">&lt;/notifications&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>In this configuration, all queries containing "mysqldb." are sent to the connectionid "mysqldb" and all queries containing "postgresqldb." are sent to the connectionid "postgresqldb".</p>

<p>As above, the <b>string</b> parameter in each connection tag provides the parameters necessary to connect to the other instances.</p>

<p>Note the use of a notification module, as above.</p>

<br/><a name="userlist"/><h4>userlist</h4>

<p>The <b>userlist</b> module routes queries by matching the user that ran the query against a list of users.</p>

<p>An example configuration follows.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

        <i><font color="#9A1900">&lt;!-- This instance maintains connections to an Oracle database. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"oracle"</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/oracle.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"oracle"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"oracleuser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"oraclepassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
                <b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>


        <i><font color="#9A1900">&lt;!-- This instance maintains connections to an SAP database. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"sap"</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/sap.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"sap"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sapuser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sappassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
                <b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"sybase=/opt/sap;lang=en_US;server=TESTDB;user=testuser;password=testpassword;db=testdb;"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>


        <i><font color="#9A1900">&lt;!-- This instance sends one set of users to the Oracle database and</font></i>
<i><font color="#9A1900">                all other users to the sap database. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"router"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"router"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"oracleuser1"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"oraclepassword"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"oracleuser2"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"oraclepassword"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"oracleuser3"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"oraclepassword"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"oracleuser4"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"oraclepassword"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sapuser1"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sappassword"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sapuser2"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sappassword"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sapuser3"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sappassword"</font><b><font color="#0000FF">/&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sapuser4"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sappassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;routers&gt;</font></b>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"userlist"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"oracle"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"oracleuser1"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"oracleuser2"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"oracleuser3"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"oracleuser4"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"userlist"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"sap"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"*"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
		<b><font color="#0000FF">&lt;/routers&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"oracle"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/oracle.socket;user=oracleuser;password=oraclepassword"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"sap"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/sap.socket;user=sapuser;password=sappassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>In this example, 3 SQL Relay instances are defined:</p>

<ul>
  <li>one to maintain connections to an Oracle database</li>
  <li>one to maintain connections to a SAP database</li>
  <li>one to route queries to the other two instances</li>
</ul>

<p>In this configuration, queries made by "oracle users" are routed to the connectionid "oracle", and all other queries are routed to the connectionid "sap".</p>

<p>The <b>string</b> parameter in each connection tag provides the parameters necessary to connect to the other instances.  Valid parameters include:</p>

<ul>
  <li><b>host</b> - the host name or IP address of the SQL Relay instance</li>
  <li><b>port</b> - the port of the SQL Relay instance</li>
  <li><b>socket</b> - the socket of the SQL Relay instance, if it is running locally</li>
  <li><b>user</b> - the user to use when connecting to the SQL Relay instance as</li>
  <li><b>password</b> - the password to use when connecting to the SQL Relay instance</li>
  <li><b>fetchatonce</b> - the number of rows to fetch at a time (defaults to 10, 0 means fetch the entire result set)</li>
</ul>

<br/><br/><a name="clientiplist"/><h4>clientiplist</h4>

<p>The <b>clientiplist</b> module routes queries by matching the client that ran the query against a list of IP addresses.</p>

<p>An example configuration follows.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

        <i><font color="#9A1900">&lt;!-- This instance maintains connections to an Oracle database. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"oracle"</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/oracle.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"oracle"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"oracleuser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"oraclepassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
                <b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>


        <i><font color="#9A1900">&lt;!-- This instance maintains connections to an SAP database. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"sap"</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/sap.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"sap"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sapuser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sappassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
                <b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"sybase=/opt/sap;lang=en_US;server=TESTDB;user=testuser;password=testpassword;db=testdb;"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>


        <i><font color="#9A1900">&lt;!-- This instance sends one set of users to the Oracle database and</font></i>
<i><font color="#9A1900">                all other users to the sap database. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"router"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"router"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"routeruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"routerpassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;routers&gt;</font></b>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"clientiplist"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"master"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;client</font></b> <font color="#009900">ip</font><font color="#990000">=</font><font color="#FF0000">"192.168.*.0-50"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"clientiplist"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"slave"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;client</font></b> <font color="#009900">ip</font><font color="#990000">=</font><font color="#FF0000">"*"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
		<b><font color="#0000FF">&lt;/routers&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"oracle"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/oracle.socket;user=oracleuser;password=oraclepassword"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"sap"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/sap.socket;user=sapuser;password=sappassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>In this example, 3 SQL Relay instances are defined:</p>

<ul>
  <li>one to maintain connections to an Oracle database</li>
  <li>one to maintain connections to a SAP database</li>
  <li>one to route queries to the other two instances</li>
</ul>

<p>In this configuration, queries made by users originating at IP addresses 192.168.*.0-50 are routed to the connectionid "oracle", and queries made by users originating at all other IP addresses are routed to the connectionid "sap".</p>

<p>Each octet of the <b>ip</b> parameter may be specfied as a number, a dash-separated range of numbers, or a * meaning "all possible values".</p>

<p>The <b>string</b> parameter in each connection tag provides the parameters necessary to connect to the other instances.  Valid parameters include:</p>

<ul>
  <li><b>host</b> - the host name or IP address of the SQL Relay instance</li>
  <li><b>port</b> - the port of the SQL Relay instance</li>
  <li><b>socket</b> - the socket of the SQL Relay instance, if it is running locally</li>
  <li><b>user</b> - the user to use when connecting to the SQL Relay instance as</li>
  <li><b>password</b> - the password to use when connecting to the SQL Relay instance</li>
  <li><b>fetchatonce</b> - the number of rows to fetch at a time (defaults to 10, 0 means fetch the entire result set)</li>
</ul>

<br/><br/><a name="clientinfolist"/><h4>clientinfolist</h4>

<p>The <b>clientinfolist</b> module routes queries by matching the "client info" sent by the client against a list of regular expressions.  The client info can be set using the setClientInfo() method/function provided by the native SQL Relay client API.  The client info cannot currently be set when using a connector for a database abstraction later such as PHP PDO or ODBC.</p>

<p>An example configuration follows.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

        <i><font color="#9A1900">&lt;!-- This instance maintains connections to an Oracle database. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"oracle"</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/oracle.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"oracle"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"oracleuser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"oraclepassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
                <b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>


        <i><font color="#9A1900">&lt;!-- This instance maintains connections to an SAP database. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"sap"</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/sap.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"sap"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sapuser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sappassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
                <b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"sybase=/opt/sap;lang=en_US;server=TESTDB;user=testuser;password=testpassword;db=testdb;"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>


        <i><font color="#9A1900">&lt;!-- This instance sends one set of users to the Oracle database and</font></i>
<i><font color="#9A1900">                all other users to the sap database. --&gt;</font></i>
        <b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"router"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"router"</font><b><font color="#0000FF">&gt;</font></b>
                <b><font color="#0000FF">&lt;users&gt;</font></b>
                        <b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"routeruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"routerpassword"</font><b><font color="#0000FF">/&gt;</font></b>
                <b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;routers&gt;</font></b>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"clientinfolist"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"master"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;client</font></b> <font color="#009900">ip</font><font color="#990000">=</font><font color="#FF0000">".*oracle.*"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;client</font></b> <font color="#009900">ip</font><font color="#990000">=</font><font color="#FF0000">".*orcl.*"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"clientinfolist"</font> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"slave"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;client</font></b> <font color="#009900">ip</font><font color="#990000">=</font><font color="#FF0000">"*"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
		<b><font color="#0000FF">&lt;/routers&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"oracle"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/oracle.socket;user=oracleuser;password=oraclepassword"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"sap"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/sap.socket;user=sapuser;password=sappassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
        <b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>In this example, 3 SQL Relay instances are defined:</p>

<ul>
  <li>one to maintain connections to an Oracle database</li>
  <li>one to maintain connections to a SAP database</li>
  <li>one to route queries to the other two instances</li>
</ul>

<p>In this configuration, queries made by users who send client info which contains the string "oracle" or "orcl" to the connectionid "oracle", and queries made by users sending any other client info the connectionid "sap".</p>

<p>The <b>string</b> parameter in each connection tag provides the parameters necessary to connect to the other instances.  Valid parameters include:</p>

<ul>
  <li><b>host</b> - the host name or IP address of the SQL Relay instance</li>
  <li><b>port</b> - the port of the SQL Relay instance</li>
  <li><b>socket</b> - the socket of the SQL Relay instance, if it is running locally</li>
  <li><b>user</b> - the user to use when connecting to the SQL Relay instance as</li>
  <li><b>password</b> - the password to use when connecting to the SQL Relay instance</li>
  <li><b>fetchatonce</b> - the number of rows to fetch at a time (defaults to 10, 0 means fetch the entire result set)</li>
</ul>

<br/><br/><a name="usedatabase"/><h4>usedatabase</h4>

<p>The <b>usedatabase</b> allows you to access databases across multiple database instances via the same SQL Relay front-end with "use database" queries.</p>

<p>For example, lets say you have two database instances:</p>

<p>A MySQL instance that hosts 3 databases:</p>

<ul>
  <li>mydb1</li>
  <li>mydb2</li>
  <li>mydb3</li>
</ul>

<p>...and a PostgreSQL instance that hosts 2 databases:</p>

<ul>
  <li>pg1</li>
  <li>pg2</li>
</ul>

<p>If you configure an instance of SQL Relay to access the MySQL instance, then a SQL Relay client can run queries like "use mydb1" or "use mydb2" to select the database.</p>

<p>Similarly, if you configure an instance of SQL Relay to access the PostgreSQL instance, then a SQL Relay client can run queries like "use pbdb1" or "use pbdb2" to select the database.</p>

<p>The <b>usedatabase</b> module allows a client connected to a single instance of SQL Relay to select the database across both instances.  For example, "use mydb1" would set the current database to the mydb1 database hosted by the MySQL instance, and "use pgdb2" would set the current database to the pgdb2 database hosted by the PostgreSQL instance.</p>

<p>An example configuration follows.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<i><font color="#9A1900">&lt;!-- This instance maintains connections to a MySQL database --&gt;</font></i>
	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"mysqldb"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">""</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/mysqldb.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"mysql"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"mysqldbuser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"mysqldbpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=mysqldbuser;password=mysqldbpassword;host=mysqldb;db=mysqldb;"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>


	<i><font color="#9A1900">&lt;!-- This instance maintains connections to a PostgreSQL database --&gt;</font></i>
	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"postgresqldb"</font> <font color="#009900">port</font><font color="#990000">=</font><font color="#FF0000">""</font> <font color="#009900">socket</font><font color="#990000">=</font><font color="#FF0000">"/tmp/postgresqldb.socket"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"postgresql"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"postgresqldbuser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"postgresqldbpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=postgresqldbuser;password=postgresqldbpassword;host=postgresqldb;db=postgresqldb;"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>


	<i><font color="#9A1900">&lt;!-- This instance sends queries to databases hosted by the mysql</font></i>
<i><font color="#9A1900">		instance and postgresql instance based on "use ..." queries. --&gt;</font></i>
	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"router"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"router"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"routeruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"routerpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;routers&gt;</font></b>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"usedatabase"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/routers&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"mysqldb"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/mysqldb.socket;user=mysqldbuser;password=mysqldbpassword"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"postgresqldb"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/postgresqldb.socket;user=postgresqldbuser;password=postgresqldbpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>In this example, 3 SQL Relay instances are defined:</p>

<ul>
  <li>one to maintain connections to an MySQL instance</li>
  <li>one to maintain connections to a PostgreSQL database</li>
  <li>one to route queries to the other two instances</li>
</ul>

<p>The <b>string</b> parameter in each connection tag provides the parameters necessary to connect to the other instances.  Valid parameters include:</p>

<ul>
  <li><b>host</b> - the host name or IP address of the SQL Relay instance</li>
  <li><b>port</b> - the port of the SQL Relay instance</li>
  <li><b>socket</b> - the socket of the SQL Relay instance, if it is running locally</li>
  <li><b>user</b> - the user to use when connecting to the SQL Relay instance as</li>
  <li><b>password</b> - the password to use when connecting to the SQL Relay instance</li>
  <li><b>fetchatonce</b> - the number of rows to fetch at a time (defaults to 10, 0 means fetch the entire result set)</li>
</ul>

<p>When the router instance starts, it gets the list of databases available from each of the other two instances, and routes to them accordingly.</p>

<p>A sample sqlrsh session follows:</p>

<blockquote>
  <pre>sqlrsh -host localhost -user routeruser -password routerpassword
sqlrsh - Version 1.1.0
        Connected to: localhost:9000 as routeruser

        type help; for help.

0> use mydb1;
0> currentdb;
mydb1
0> select * from testtable;
col1
==========================
this table is in db mydb1

        Rows Returned   : 1
        Fields Returned : 1
        Elapsed Time    : 0.001512 sec

0> use mydb2;
0> currentdb;
mydb2
0> select * from testtable;
col1
==========================
this table is in db mydb2

        Rows Returned   : 1
        Fields Returned : 1
        Elapsed Time    : 0.001512 sec

0> use pgdb1;
0> currentdb;
pgdb1
0> select * from testtable;
col1
==========================
this table is in db pgdb1

        Rows Returned   : 1
        Fields Returned : 1
        Elapsed Time    : 0.001344 sec

0>
</pre>

</blockquote>
<p>But...  What if two different instances host databases with the same name?  For example, what if your MySQL instance hosts a database named db2, and your PostgreSQL instance also hosts a database named db2?</p>

<p>To resolve situations like this, the <b>usedatabase</b> module allows you to map a database to an alias.  In this example, the db2 database hosted by MySQL is mapped to mydb2, and the db2 database hosted by PostgreSQL is mapped to pgdb2.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	... MySQL/PostgreSQL instance details omitted ...

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"router"</font> <font color="#009900">dbase</font><font color="#990000">=</font><font color="#FF0000">"router"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"routeruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"routerpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;routers&gt;</font></b>
			<b><font color="#0000FF">&lt;router</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"usedatabase"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;map</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"mysqldb"</font> <font color="#009900">db</font><font color="#990000">=</font><font color="#FF0000">"db2"</font> <font color="#009900">alias</font><font color="#990000">=</font><font color="#FF0000">"mydb2"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;map</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"postgresqldb"</font> <font color="#009900">db</font><font color="#990000">=</font><font color="#FF0000">"db3"</font> <font color="#009900">alias</font><font color="#990000">=</font><font color="#FF0000">"pgdb3"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;/router&gt;</font></b>
		<b><font color="#0000FF">&lt;/routers&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"mysqldb"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/mysqldb.socket;user=mysqldbuser;password=mysqldbpassword"</font><b><font color="#0000FF">/&gt;</font></b>
			<b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">connectionid</font><font color="#990000">=</font><font color="#FF0000">"postgresqldb"</font> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"socket=/tmp/postgresqldb.socket;user=postgresqldbuser;password=postgresqldbpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>To access the db2 database hosted by MySQL, the user would run:</p>

<blockquote>
  <pre>use mydb2
</pre>

</blockquote>
<p>To access the db2 database hosted by PostgreSQL, the user would run:</p>

<blockquote>
  <pre>use pgdb2
</pre>

</blockquote>
<p>Attempts to "use db2" would fail.</p>

<br/><a name="routingquirks"/><h3>Quirks and Limitations</h3>

<h4>Query Normalization</h4>

<p>To make pattern matching easier, SQL Relay "normalizes" the query before
matching it against the pattern.  The original query is run against the database
but when matched against the pattern, whitespace is compresssed and the entire
query (except for quoted strings) is converted to lower-case.</p>

<p>When matching query operators, you must use lower-cased versions of them such
as "select", "insert", "and", "or", etc.  When matching table names, you must
use a lower-cased version of the table-name.</p>

<h4>Perl Compatible Regular Expressions</h4>

<p>SQL Relay is built upon the Rudiments library.  Rudiments can be built with
or without support for libpcre which provides support for Perl Compatible
Regular Expressions.  PCRE's are more powerful than standard posix regular
expressions and have many more operators.</p>

<p>As such, if you copy a configuration file from a machine where Rudiments was
compiled with PCRE support to a machine where Rudiments wasn't compiled with
PCRE support, then it's possible that your patterns may not work on the new
machine.</p>

<p>To make matters worse, sufficiently old versions of the posix regular
expression functions had fewer operators than modern versions.  So, even if
Rudiments isn't using PCRE's, it's not impossible that after copying a
configuration file from a fairly modern OS to an antique, the patterns won't
work on the antique machine either.</p>

<p>The examples above ought to work with PCRE's and all versions of posix
regular expressions.</p>

<h4>Selects Not Showing Changes</h4>

<p>In the scenario above where DML/DDL is sent to the master database and
selects are distributed over slaves, an unintuitive thing can happen.</p>

<p>If you begin a transaction and do several inserts, updates and deletes,
you'll find that if you do a select, you will not see your changes.  This is
because in a master-slave configuration, changes to the database are not
pushed out to the slaves until the changes have been committed.  Since your
selects are being run against the slaves, you must first commit before your
changes will be visible.</p>

<h4>Stored Procedures</h4>

<p>It's possible to use stored procedures with SQL Relay's query routing
feature.  However, since stored procedures are run on the database, SQL Relay
can't route the individual queries run inside the stored procedure.  So, the
stored procedure and all queries run inside of it will be run against whichever
database it was routed to.</p>

<h4>Parallel Transactions</h4>

<p>Router modules like <b>userlist</b>, <b>clientiplist</b>, and <b>clientinfolist</b>
route entire sessions to one database or another.  Router modules like
<b>regex</b> route individual queries.  Behind the scenes, modules which route
individual queries maintain parallel transactions on each of the databases that
it is routing queries to, which present the following issues.</p>

<p><b>Integrity Violations</b></p>

<p>When the client issues a begin, commit or rollback, the router issues a begin,
commit or rollback to each of the databases.  Similarly, if the client turns
auto-commit on or off, the router turns auto-commit on or off on each of the
databases.</p>

<p>There are scenarios where a commit, rollback or auto-commit on/off command
could succeed on some of the databases and fail on others.  Some databases
have a 2-phase commit feature to handle these scenarios.  With 2-phase commit,
you can roll back a commit until you do second commit.  Many databases don't
support 2-phase commit though.  At present, SQL Relay doesn't currently support
2-phase commit for any database.  So, currently, to handle this situation,
SQL Relay returns an error, disables the instance doing the query routing, and
raises an integrity_violation event.  If a notification is configured to notify
a DBA when an integrity_violation is raised, then the DBA will receive an
email about the problem.  Unfortunately, there is no standard way to solve
the problem.  The DBA must determine the cause, resolve it manually, and restart
SQL Relay.</p>

<p><b>Commits and Rollbacks</b></p>

<p>Since queries may be routed to different kinds of databases, the router has
to employ some tricks to maintain parallel transactions on dissimilar
databases.  Some databases run in auto-commit mode by default and must be
issued a "begin" query to start a transaction.  Other databases implicitly
start a new transaction when a client logs in and after each commit or rollback.
If any of the databases being routed to require a "begin" query to start a
transaction, then the ones that don't are put in auto-commit mode when the
client logs in and after each commit or rollback and are taken out of
auto-commit mode when the client sends a begin query.  If none of the databases
being routed to require a "begin" query to start a transaction, then the
databases are not put in auto-commit mode when the client logs in or after each
commit or rollback.  Rather, transactions are implicitly started by the
database.  For example, if your client application is using a router which
routes queries over both PostgreSQL and Oracle databases, then since
PostgreSQL requires "begin" queries, you must use a "begin" query to start a
transaction, even if your app only intends to send queries which would be run
against Oracle.  Conversely, if your client application is using a router which
only routes queries over a set of Oracle databases, then you do not have to use
"begin" queries.</p>

<hr/>

<br/><a name="logging"/><h2>Logging</h2>

<p>Logging allows the SQL Relay server programs to log various bits of information as they run.</p>

<p>Logging is implemented by loadable modules.  The <i>loggers</i> section of the configuration file indicates which modules to load and what parameters to use when executing them.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>
 
	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;loggers&gt;</font></b>
			<b><font color="#0000FF">&lt;logger</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"debug"</font> <font color="#009900">listener</font><font color="#990000">=</font><font color="#FF0000">"yes"</font> <font color="#009900">connection</font><font color="#990000">=</font><font color="#FF0000">"yes"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/loggers&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The <i>module</i> attribute specifies which module to load.</p>

<p>Module configurations may have attributes and/or nested tags.  How these are interpreted is module-specific.</p>

<p>Different modules may have different parameters.  In this example, listener="yes" tells the module to log debug info for the sqlr-listener processes and connection="yes" tells the module to log debug info for the sqlr-connection processes.</p>

<p>All logger modules have an <i>enabled</i> parameter, allowing the module to be temporarily disabled.  If enabled="no" is configured, then the module is disabled.  If set to any other value, or omitted, then the module is enabled.</p>

<p>Logger modules can be "stacked".  Multiple different modules may be loaded and multiple instances of the same type of module, with different configurations, may also be loaded.</p>

<p>At startup, the SQL Relay server processes create instances of the specified logger modules and initialize them.  As events occur, the server passes the event, log level, and optionally, a string of information about the event to each module, in the order that they were specified in the config file.  If a module is listening for that event, at that log level, then it logs information about the event to a log file.</p>

<p>Currently, the following standard logger modules are available:</p>

<ul>
  <li><b>debug</b></li>
  <li><b>slowqueries</b></li>
</ul>

<p>Custom modules may also be developed.  For more information, please contact <a href="mailto:dev@firstworks.com">dev@firstworks.com</a>. <a target="_blank" href="http://sqlrelay.sourceforge.net/images/us.png"><img src="http://sqlrelay.sourceforge.net/images/us.png"/></a> <a target="_blank" href="http://sqlrelay.sourceforge.net/images/br.png"><img src="http://sqlrelay.sourceforge.net/images/br.png"/></a></p>

<h4>debug</h4>

<p>The <b>debug</b> module logs a great deal of information to about the internal operation of the SQL Relay server to log files in the "debug directory", usually /usr/local/firstworks/var/log/sqlrelay/debug or /usr/local/firstworks/var/sqlrelay/debug.  It creates files named sqlr-listener."pid" and sqlr-connection."pid" where "pid" is replaced with the process id of the process that is being logged.  As new processes are forked, new files are created with debug information about those processes.</p>

<p>This module takes three parameters: <b>listener</b>, <b>connection</b> and <b>perms</b>.  The <b>listener</b> parameter may be set to "no" to disable logging of the sqlr-listener processes.  The <b>connection</b> parameter may be set to "no" to disable logging of the sqlr-connection processes.  Logging is enabled if either parameter is omitted or set to any other value.  The <b>perms</b> parameter may be set to any ls -l style permissions string.  The default is "rw-------" which translates to read/write for owner only.</p>

<p>The general log format is:</p>

<blockquote>
  <pre>mm/dd/yyyy hh:mm:ss TZ processname [pid] : info
</pre>

</blockquote>
<p>Sample log for main listener process: <a href="sqlr-listener.1869.html">sqlr-listener.1869</a><br/>
Sample log for child listener process: <a href="sqlr-listener.1886.html">sqlr-listener.1886</a><br/>
Sample log for connecton process: <a href="sqlr-connection.1871.html">sqlr-connection.1871</a><br/></p>

<h4>slowqueries</h4>

<p>The <b>slowqueries</b> module logs queries that take longer to run than a specified threshold to log files in the "log directory", usually /usr/local/firstworks/var/log/sqlrelay or /usr/local/firstworks/var/sqlrelay/log.  It creates files named sqlr-connection-"id"-querylog."pid" for each sqlr-connection process where "id" is replaced with the id of the instance from the configuration file and "pid" is replaced with the process id.</p>

<p>This module takes two parameters: <b>sec</b> and <b>usec</b>.  Queries that take longer than <b>sec</b> seconds and <b>usec</b> microseconds will be logged.  Both parameters default to 0 and omitting them causes all queries to be logged.</p>

<p>The general format is:</p>

<blockquote>
  <pre>Mon 2014 Apr  6 15:58:17 :
select 1 from dual
time: 0.000001
</pre>

</blockquote>
<p>Sample log: <a href="sqlr-connection-oracletest-querylog.2899.html">sqlr-connection-oracletest-querylog.2899</a></p>

<hr/>

<br/><a name="notifications"/><h2>Notifications</h2>

<p>Notifications allow the SQL Relay server programs to notify recipients when a specified set of events occur. </p>

<p>Notifications are implemented by loadable modules.  The <i>notifications</i> section of the configuration file indicates which notification modules to load and what parameters to use when executing them.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;notifications&gt;</font></b>
			<b><font color="#0000FF">&lt;notification</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"events"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;events&gt;</font></b>
					<b><font color="#0000FF">&lt;event</font></b> <font color="#009900">event</font><font color="#990000">=</font><font color="#FF0000">"db_error"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;event</font></b> <font color="#009900">event</font><font color="#990000">=</font><font color="#FF0000">"db_warning"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;event</font></b> <font color="#009900">event</font><font color="#990000">=</font><font color="#FF0000">"filter_violation"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/events&gt;</font></b>
				<b><font color="#0000FF">&lt;recipients&gt;</font></b>
					<b><font color="#0000FF">&lt;recipient</font></b> <font color="#009900">address</font><font color="#990000">=</font><font color="#FF0000">"dev@firstworks.com"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/recipients&gt;</font></b>
			<b><font color="#0000FF">&lt;/notification&gt;</font></b>
		<b><font color="#0000FF">&lt;/notifications&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>The <i>module</i> attribute specifies which module to load.</p>

<p>Module configurations may have attributes and/or nested tags.  How these are interpreted is module-specific.</p>

<p>All notification modules have an <i>enabled</i> parameter, allowing the module to be temporarily disabled.  If enabled="no" is configured, then the module is disabled.  If set to any other value, or omitted, then the module is enabled.</p>

<p>Notification modules can be "stacked".  Multiple different modules may be loaded and multiple instances of the same type of module, with different configurations, may also be loaded.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;notifications&gt;</font></b>
			<b><font color="#0000FF">&lt;notification</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"events"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;events&gt;</font></b>
					<b><font color="#0000FF">&lt;event</font></b> <font color="#009900">event</font><font color="#990000">=</font><font color="#FF0000">"db_error"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;event</font></b> <font color="#009900">event</font><font color="#990000">=</font><font color="#FF0000">"db_warning"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;event</font></b> <font color="#009900">event</font><font color="#990000">=</font><font color="#FF0000">"filter_violation"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/events&gt;</font></b>
				<b><font color="#0000FF">&lt;recipients&gt;</font></b>
					<b><font color="#0000FF">&lt;recipient</font></b> <font color="#009900">address</font><font color="#990000">=</font><font color="#FF0000">"dev@firstworks.com"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/recipients&gt;</font></b>
			<b><font color="#0000FF">&lt;/notification&gt;</font></b>
			<b><font color="#0000FF">&lt;notification</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"events"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;events&gt;</font></b>
					<b><font color="#0000FF">&lt;event</font></b> <font color="#009900">event</font><font color="#990000">=</font><font color="#FF0000">"integrity_violation"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/events&gt;</font></b>
				<b><font color="#0000FF">&lt;recipients&gt;</font></b>
					<b><font color="#0000FF">&lt;recipient</font></b> <font color="#009900">address</font><font color="#990000">=</font><font color="#FF0000">"dba@firstworks.com"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/recipients&gt;</font></b>
			<b><font color="#0000FF">&lt;/notification&gt;</font></b>
		<b><font color="#0000FF">&lt;/notifications&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>At startup, the SQL Relay server processes create instances of the specified notification modules and initializes them.  As events occur, the server passes the event and, optionally, a string of information about the event to each module, in the order that they were specified in the config file.  If a module is listening for that event, then it sends a notification to the specified recpients.</p>

<p>Currently, the following standard notification module is available:</p>

<ul>
  <li><b>events</b></li>
</ul>

<p>Custom modules may also be developed.  For more information, please contact <a href="mailto:dev@firstworks.com">dev@firstworks.com</a>. <a target="_blank" href="http://sqlrelay.sourceforge.net/images/us.png"><img src="http://sqlrelay.sourceforge.net/images/us.png"/></a> <a target="_blank" href="http://sqlrelay.sourceforge.net/images/br.png"><img src="http://sqlrelay.sourceforge.net/images/br.png"/></a></p>

<p>The <b>events</b> module listens for a specified set of events and notifies recipients when a one occurs.</p>

<p>An example configuration follows.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> ...<b><font color="#0000FF">&gt;</font></b>
		...
		<b><font color="#0000FF">&lt;notifications&gt;</font></b>
			<b><font color="#0000FF">&lt;notification</font></b> <font color="#009900">module</font><font color="#990000">=</font><font color="#FF0000">"events"</font><b><font color="#0000FF">&gt;</font></b>
				<b><font color="#0000FF">&lt;events&gt;</font></b>
					<b><font color="#0000FF">&lt;event</font></b> <font color="#009900">event</font><font color="#990000">=</font><font color="#FF0000">"db_error"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;event</font></b> <font color="#009900">event</font><font color="#990000">=</font><font color="#FF0000">"db_warning"</font><b><font color="#0000FF">/&gt;</font></b>
					<b><font color="#0000FF">&lt;event</font></b> <font color="#009900">event</font><font color="#990000">=</font><font color="#FF0000">"filter_violation"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/events&gt;</font></b>
				<b><font color="#0000FF">&lt;recipients&gt;</font></b>
					<b><font color="#0000FF">&lt;recipient</font></b> <font color="#009900">address</font><font color="#990000">=</font><font color="#FF0000">"dev@firstworks.com"</font><b><font color="#0000FF">/&gt;</font></b>
				<b><font color="#0000FF">&lt;/recipients&gt;</font></b>
			<b><font color="#0000FF">&lt;/notification&gt;</font></b>
		<b><font color="#0000FF">&lt;/notifications&gt;</font></b>
		...
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>In this example, the module sends notifications to <b>dev@firstworks.com</b> when one of the <b>db_error</b>, <b>db_warning</b>, or <b>filter_violation</b> events occurs.</p>

<p>The <b>events</b> tag defines the set of events to listen for.  Valid events are:</p>

<ul>
  <li><b>client_connected</b> - An SQL Relay client connected to the SQL Relay server.</li>
  <li><b>client_connection_refused</b> - An SQL Relay client attempted to connect to the SQL Relay server but the server refused the connection, usually because authentication failed.</li>
  <li><b>client_disconnected</b> - An SQL Relay client disconnected from the SQL Relay server.</li>
  <li><b>client_protocol_error</b> - The SQL Relay server didn't understand something that the SQL Relay client sent to it.</li>
  <li><b>db_login</b> - The SQL Relay server opened a connection to the database.</li>
  <li><b>db_logout</b> - The SQL Relay server closed a connection to the database.</li>
  <li><b>db_error</b> - A query generated an error.</li>
  <li><b>db_warning</b> - A query generated a warning.</li>
  <li><b>query</b> - A query was executed.</li>
  <li><b>filter_violation</b> - A <a href="#filtering">query filter module</a> prevented a query from being executed.</li>
  <li><b>internal_error</b> - An internal error occurred.</li>
  <li><b>internal_warning</b> - An internal warning occurred.</li>
  <li><b>debug_message</b> - A debug message was generated.</li>
  <li><b>schedule_violation</b> - A <a href="#schedules">connection schedule module</a> prevented a user from logging in to the SQL Relay server.</li>
  <li><b>integrity_violation</b> - A <a href="#queryrouting">query routing module</a> is in use and a transaction control query (begin, commit, rollback, autocommit on, or autocommit off) succeeded on some of the backends but failed on others.</li>
</ul>

<p>Any number of events may be specified.  Each event must be specified in its own <b>event</b> tag.  The event tag supports the following attributes:</p>

<ul>
  <li><b>event</b> - Required.  The event to listen for.</li>
</ul>

<p>Any number of recipients may also be specified.  Each recipient must be specified in its own <b>recipient</b> tag.  The recipient tag supports the following attributes:</p>

<ul>
  <li><b>address</b> - Required.  The address to send the notification message to.</li>
  <li><b>subject</b> - Optional.  The subject of the notification message.</li>
  <li><b>template</b> - Optional.  The filename of the template to use for the notification message.</li>
</ul>

<p>Currently, notifications may only be sent via email.</p>

<p>If the <b>subject</b> attribute is not provided, then SQL Relay uses a default subject of:</p>

<blockquote>
SQL Relay Notification: @event@
</blockquote>
<p>Where @event@ is replaced with the event that triggered the notification.</p>

<p>If the <b>template</b> attribute is not provided, then SQL Relay uses a default template of:</p>

<blockquote>
  <pre>SQL Relay Notification:

Event          : @event@
Event Info     : @eventinfo@
Date           : @datetime@
Host Name      : @hostname@
Instance       : @instance@
Process Id     : @pid@
Client Address : @clientaddr@
Client Info    : @clientinfo@
User           : @user@
Query          :
@query@
</pre>

</blockquote>
<p>In both subject lines and template files, the following substitutions can be made:</p>

<ul>
  <li><b>@event@</b> - The event that triggered the notification.</li>
  <li><b>@eventinfo@</b> - The text (if any) that accompanied the event.</li>
  <li><b>@datetime@</b> - The date/time that the event occurred.</li>
  <li><b>@hostname@</b> - The host name of the server hosting the SQL Relay instance that generated the event.</li>
  <li><b>@instance@</b> - The instance name of the SQL Relay instance that generated the event.</li>
  <li><b>@pid@</b> - The process id of the SQL Relay instance that generated the event.</li>
  <li><b>@clientaddr@</b> - The client address (if any) of the SQL Relay client that was connected when the event occurred.</li>
  <li><b>@clientinfo@</b> - The client info (if any) of the SQL Relay client that was connected when the event occurred.</li>
  <li><b>@user@</b> - The SQL Relay user (if any) that was logged in to the SQL Relay instance that generated the event.</li>
  <li><b>@query@</b> - The query (if any) that was running when the event occurred.</li>
</ul>

<p>On linux/unix systems, the <i>mail</i> program is used to send notifications.  Messages are sent using the following command:</p>

<blockquote>
mail -s <i>subject</i> <i>address</i> < <i>message</i>
</blockquote>
<p>Where <i>subject</i> is replaced with the subject, <i>address</i> is replaced with the recipient and <i>messagee</i> is replaced with the name of the temporary file that is used to store the message.</p>

<p>SQL Relay assumes that the <i>mail</i> program is installed, in the PATH of the user that SQL Relay runs as, and that mail delivery is configured on the host system.</p>

<p>On Windows systems the <i>blat</i> program is used to send notifications.  Messages are sent using the following command:</p>

<blockquote>
blat <i>message</i> -to <i>address</i> -subject <i>subject</i> -q
</blockquote>
<p>Where <i>subject</i> is replaced with the subject, <i>address</i> is replaced with the recipient and <i>message</i> is replaced with the name of the temporary file that is used to store the message.</p>

<p>SQL Relay assumes that the <i>blat</i> program is installed, in the PATH of the user that SQL Relay runs as, and that blat has been configured.  See <a target="_blank" href="http://www.blat.net">http://www.blat.net</a> to download and configure blat.</p>

<hr/>

<br/><a name="sessionqueries"/><h2>Session-Queries</h2>

<p>SQL Relay can be configured to run a set of queries at the beginning and end of each client session.</p>

<p>By far the most common use for this feature is that some database parameter needs to be reconfigured but you don't have permission or bouncing the database is out of the question, or something like that.  For example, lets say you are using an Oracle database, but your app requires dates to be formatted like MM/DD/YYYY instead of DD-MON-YYYY.  Ideally you'd alter the nls_date_format in the instance but you can't, for some reason.</p>

<p>You can use SQL Relay's session queries to work around the problem.</p>

<p>In the following example, the date format is set to MM/DD/YYYY at the beginning of the session and then reset back to DD-MON-YYYY at the end.</p>

<blockquote>
<!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000080">&lt;?xml</font></b> <font color="#009900">version</font><font color="#990000">=</font><font color="#FF0000">"1.0"</font><b><font color="#000080">?&gt;</font></b>
<b><font color="#0000FF">&lt;instances&gt;</font></b>

	<b><font color="#0000FF">&lt;instance</font></b> <font color="#009900">id</font><font color="#990000">=</font><font color="#FF0000">"example"</font><b><font color="#0000FF">&gt;</font></b>
		<b><font color="#0000FF">&lt;users&gt;</font></b>
			<b><font color="#0000FF">&lt;user</font></b> <font color="#009900">user</font><font color="#990000">=</font><font color="#FF0000">"sqlruser"</font> <font color="#009900">password</font><font color="#990000">=</font><font color="#FF0000">"sqlrpassword"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/users&gt;</font></b>
		<b><font color="#0000FF">&lt;session&gt;</font></b>
			<b><font color="#0000FF">&lt;start&gt;</font></b>
				<b><font color="#0000FF">&lt;runquery&gt;</font></b>alter session set nls_date_format='MM/DD/YYYY'<b><font color="#0000FF">&lt;/runquery&gt;</font></b>
			<b><font color="#0000FF">&lt;/start&gt;</font></b>
			<b><font color="#0000FF">&lt;end&gt;</font></b>
				<b><font color="#0000FF">&lt;runquery&gt;</font></b>alter session set nls_date_format='DD-MON-YYYY'<b><font color="#0000FF">&lt;/runquery&gt;</font></b>
			<b><font color="#0000FF">&lt;/end&gt;</font></b>
		<b><font color="#0000FF">&lt;/session&gt;</font></b>
		<b><font color="#0000FF">&lt;connections&gt;</font></b>
                        <b><font color="#0000FF">&lt;connection</font></b> <font color="#009900">string</font><font color="#990000">=</font><font color="#FF0000">"user=scott;password=tiger;oracle_sid=orcl"</font><b><font color="#0000FF">/&gt;</font></b>
		<b><font color="#0000FF">&lt;/connections&gt;</font></b>
	<b><font color="#0000FF">&lt;/instance&gt;</font></b>

<b><font color="#0000FF">&lt;/instances&gt;</font></b>
</tt></pre>

</blockquote>
<p>Actually, in this example, there's no need to set the date format back to DD-MON-YYYY but it's done here for illustrative purposes.</p>

<hr/>

<br/><a name="advanced"/><h2>Advanced Configuration</h2>

<p>The configuration file supports many more attributes and features than the ones described in this guide including tuning options.  See the <a href="configreference.html">SQL Relay Configuration Reference</a> and <a href="tuning.html">Tuning SQL Relay</a> for more information.
</p>

</body>
</html>
